diff --git a/Contributing.md b/Contributing.md index a89e477..777092c 100644 --- a/Contributing.md +++ b/Contributing.md @@ -1 +1,25 @@ -# Need content \ No newline at end of file +# Contribution guide + + +## Pre-requisite of EasyCLA before Submitting Pull Requests (PR) + +In order to be able to successfully submit a pull request from your fork you need to sign with EasyCLA from Linux Foundation. +The video tutorial can be found [here, assuming you have submitted a PR without prior signing](https://youtu.be/WV9AD9QvSCY?si=RmA4Y-Ttk9weLJlE&t=1428), which would leave you stuck as in this screenshot. + + +![easycla](https://github.com/Larissa-Health/tswg-trust-registry-protocol/assets/7843228/8c711fab-32cf-42b8-8f64-ee5e9b3ab01a) + + +**Click** on the link `Please click here to be authorized` and follow the process. +You will have to login with your Linux Foundation ID (Account) or create a new one. +If you signed up with ToIP under your corporation then please select this option. +Don't worry, there won't be any changes to your membership payment status, meaning it will be still free of charge to use if you are a contributing member at ToIP. + +The process is generally quite straight forward and if you know the DocuSign-procedure, then you can fast forward the video to minute `30:36` to see the relevant action to perform if you signed EasyCLA under a corporation. + +After signing with Docusign, you will have to [connect your GitHub account with EasyCLA](https://openprofile.dev/edit/connected-accounts) (This link will get you into profile settings). + +However, the system **will not** auto generate an accepted contributing user so you will have to create one through the dashboard by adding approval criteria (screenshot below). +After you have created an identification criterium (e.g. GitHub username or email address) for yourself your PR in GitHub will automatically be submitted. + +![easycla2](https://github.com/Larissa-Health/tswg-trust-registry-protocol/assets/7843228/639ab437-d3a7-4209-8133-acc25dfeddaf) diff --git a/README.md b/README.md index de694ed..0953a05 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ # specification-template -A template for `ToIP` specifications [specification-template](https://w3c-ccg.github.io/did-spec/#specific-did-method-schemes). +This specification is basked on the [Trust Over IP Specification Template](https://github.com/trustoverip/specification-template). -The spec is written in W3C's [respec](https://dev.w3.org/2008/video/mediaann/ReSpec.js/documentation.html) format using DIF's [Spec-Up Tool](https://github.com/decentralized-identity/spec-up). -To browse the spec, see the [rendering on GitHub pages](https://trustoverip.github.io/tswg-did-method-webs-specification/index.html). To contribute to the spec, submit PRs that modify the .md files that are used to generate the .html files in this folder. +The spec is written using [SpecUp](https://github.com/decentralized-identity/spec-up) which is maintained by the Decentralized Identity Foundation. + + +To browse the spec, see the [rendering on GitHub pages](https://trustoverip.github.io/tswg-trust-registry-protocol/). To contribute to the spec, submit PRs that modify the .md files (in the `./spec` folder) that are used to generate the .html files in this folder. Before submitting a PR, please see the [Editing The Spec](./EditingTheSpec.md) document for guidance on generating the specification locally for review. @@ -15,8 +17,3 @@ To run Spec-up in live edit mode (will re-render upon save), in project folder r ``` npm run edit ``` - - - - -``` diff --git a/api/readme.md b/api/readme.md index f6c7bce..6ab6a56 100644 --- a/api/readme.md +++ b/api/readme.md @@ -10,4 +10,7 @@ npx @redocly/cli build-docs toip-tswg-trustregistryprotocol-v2.yaml --output ../ NOTE: the `--output` switch is required as SpecUp only takes content from the `./docs` folder (and below). -That produces the [Redoc Rendered OpenAPI Spec](redoc-static.html) \ No newline at end of file +That produces the [Redoc Rendered OpenAPI Spec](redoc-static.html) (NOTE: this is a local link) + +A reference to Redoc can be found [here](https://github.com/Redocly/redoc). + diff --git a/api/toip-tswg-trustregistryprotocol-v2.yaml b/api/toip-tswg-trustregistryprotocol-v2.yaml index eee70fc..17c06fd 100644 --- a/api/toip-tswg-trustregistryprotocol-v2.yaml +++ b/api/toip-tswg-trustregistryprotocol-v2.yaml @@ -596,7 +596,7 @@ components: governanceFrameworkVID: type: string format: uri - exampls: + examples: - "did:example:456" primaryTrustRegistryVID: type: string @@ -992,4 +992,4 @@ components: the problem. It may or may not yield further information if dereferenced. security: - - bearerAuth: [] \ No newline at end of file + - bearerAuth: [] diff --git a/diagrams/highlevel.plantuml b/diagrams/highlevel.plantuml index 6c6290b..7e134e3 100644 --- a/diagrams/highlevel.plantuml +++ b/diagrams/highlevel.plantuml @@ -2,7 +2,7 @@ -title Trust Over IP Trust Registry Protocol v2 Data Model - Implementer Review Draft +title Trust Over IP Trust Registry Query Protocol v2 Data Model - Implementer Review Draft package EGF { diff --git a/diagrams/protocol-bridging.plantuml b/diagrams/protocol-bridging.plantuml index 1532883..39320ba 100644 --- a/diagrams/protocol-bridging.plantuml +++ b/diagrams/protocol-bridging.plantuml @@ -1,29 +1,58 @@ @startuml -!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml +!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml ' uncomment the following line and comment the first to use locally ' !include C4_Context.puml -title Native and Bridged Support for TRP - Implementer Review Draft +title Native and Bridged Support for TRQP - Implementer Review Draft Person(Integrator, "Integrator", "Ecosystem Developer") -System(Bridge, "TR Protocol Bridge") -System(TRAIN, "TRAIN") +System(Bridge, "Generic Bridge") +System(teBridge, "DIF \n Credential Trust Establishment \nBridge","[CTE]") + +System(oidcBridge, "OIDF Bridge") +System(oidfData,"Federation","OIDF\nProfile 1") +System(oidfDataN,"Federation","OIDF\nProfile N") +Rel(Integrator, oidcBridge,"TRQP") +Rel(oidcBridge,oidfData,"OIDF\nProfile 1") +Rel(oidcBridge,oidfDataN,"OIDF\nProfile N") + +System(TRAIN, "TRAIN") +Rel(Bridge, TRAIN,"bridges") + +System_Boundary(x509system,"x509"){ + System(x509,"x509 Ecosystem") + System(x509CA,"x509 CA") + System(x509bridge, "x509 Bridge") + Rel(Integrator,x509bridge,"TRQP") + Rel(x509bridge,x509,"bridges") + Rel(x509CA, x509,"anchors") +} + + + System(EUTrustedList, "EU Trusted List") -System(NativeSupport, "SystemX"," w Native TRP Support") +System(NativeSupport, "SystemX"," w Native TRQP Support") -System(OpenDataBridge, "OpenData Bridge") -Rel(Integrator, Bridge, "TRP") -Rel(Bridge, TRAIN,"bridges") +System(teFile, "CTE file") + +Rel(teBridge, teFile,"processes") + +Rel(Integrator, Bridge, "TRQP") +Rel(Integrator, teBridge, "TRQP") + + Rel(Bridge, EUTrustedList, "bridges") -Rel(Integrator, OpenDataBridge,"TRP") -Rel(OpenDataBridge,NativeSupport,"ODPS") -Rel(Integrator, NativeSupport,"TRP") +' System(OpenDataBridge, "OpenData Bridge") +' Rel(Integrator, OpenDataBridge,"TRQP") +' Rel(OpenDataBridge,NativeSupport,"ODPS") + +Rel(Integrator, NativeSupport,"TRQP") diff --git a/docs/images/puml/protocol-bridging.png b/docs/images/puml/protocol-bridging.png index 4340ce0..5dee6ba 100644 Binary files a/docs/images/puml/protocol-bridging.png and b/docs/images/puml/protocol-bridging.png differ diff --git a/package.json b/package.json index 400478d..7db6822 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "spec-up", - "version": "0.10.6", + "version": "0.10.8", "description": "Technical specification drafting tool that generates rich specification documents from markdown.", "main": "./index", "repository": { @@ -49,7 +49,7 @@ "merge-stream": "2.0.0", "pkg-dir": "4.2.0", "prismjs": ">=1.24.0", - "spec-up": "github:brianorwhatever/spec-up#fix-refs", + "spec-up": ">=0.10.8", "yargs": "16.2.0" }, "overrides": { diff --git a/spec/annex.md b/spec/annex.md index e78e3c9..31e543d 100644 --- a/spec/annex.md +++ b/spec/annex.md @@ -33,24 +33,24 @@ The OpenAPI Specification (v3.1.0) is the first "concrete" API specification. It is provided as an Open API Specification v3 YAML file. -[OAS (.yaml) for TRP v2](../api/toip-tswg-trustregistryprotocol-v2.yaml). +[OAS (.yaml) for TRQP v2](https://github.com/trustoverip/tswg-trust-registry-protocol/blob/main/api/toip-tswg-trustregistryprotocol-v2.yaml). There are several renderings of the OAS specification: * Inline - this rendering is managed in this repository [Redoc Rendering (static HTML) of specification](./api/redoc-static.html) -* SwaggerHub - this rendering is manually updated from time to time and may be out of date: [SwaggerHub](https://app.swaggerhub.com/apis/CULedger/CULedger.Identity/0.3.1-oas3.1) +* SwaggerHub - this rendering is manually updated from time to time and may be out of date: [SwaggerHub](https://app.swaggerhub.com/apis-docs/continuumloop/trust-over_ip_trust_registry_protocol_res_tful_api_v_2/2.0.0) ## Annex C - Uses and Data Model Reference -### Use of the Trust Registry Protocol. +### Use of the Trust Registry Query Protocol. -The TRP is intended to be used in at least two key ways: +The TRQP is intended to be used in at least two key ways: -* Native Support - systems may directly implement access using the TRP. -* Bridged - systems may create access "bridges" that provide TRP access to their systems. +* Native Support - systems may directly implement access using the TRQP. +* Bridged - systems may create access "bridges" that provide TRQP access to their systems. -![C4 Systems Model - showing native TRP support on one system, bridged support to two other systems (e.g. TRAIN and EU Trusted List ARF)](./images/puml/protocol-bridging.png). +![C4 Systems Model - showing native TRQP support on one system, bridged support to two other systems (e.g. TRAIN and EU Trusted List ARF)](./images/puml/protocol-bridging.png). ### Object Model @@ -63,5 +63,5 @@ We provide a high-level object model (NOTE: source of truth is the Swagger as th We will need to provide guides and other thought pieces that explain many aspects of trust registries. A notional (short bullet) list of items could include: * "why do I need a trust registry?" - blog article or position paper to explain why trust registries help. -* "I have the data, but how do I use the TRP?" - paper about how adding TRP to a bridge or native integration. +* "I have the data, but how do I use the TRQP?" - paper about how adding TRQP to a bridge or native integration. * "where do I learn about the governance changes that I have?" \ No newline at end of file diff --git a/spec/foreword.md b/spec/foreword.md index db103ed..08dda49 100644 --- a/spec/foreword.md +++ b/spec/foreword.md @@ -7,33 +7,19 @@ [//]: # (\newpage) +## Scope +The usefulness of an ecosystem is largely dependant on its ability to assert trust for and between its members. This is true for traditional ecosystems, but even more so with digital ecosystems. With the growing trend on decentralisation of digital services, we are also seeing increased need to transitively assert trust across ecosystems. -## Foreword - -ToIP (Trust Over IP Foundation) create a _____ - -::: todo -Preamble along the lines of an ISO Foreword. -::: - -List significant changes (non-normative): - -* Shift away from a pure Issuer/Holder/Verifier approach to support non-credential use cases. -* Addition of namespacing concep to begin normalization of trust registries naming conventions. -* Enrichment of registry-of-registry concept to allow for registries that focus primarily on providing a list of registries. +The term [[ref:trust]] is loaded with varied meanings that may conflict. In the context of trust registries we want to be clear what we mean, when we apply the term “trust”. A trust registry does not create trust by itself. The decision for one entity to “trust” another is each party's own decision. The purpose of the trust registry is to provide access to a system of record that contains answers to questions that help drive those trust decisions. -### On Trust, Trustworthy, and Trustworthiness +A trust registry may provide information that helps the [[ref:consuming party]] in deciding that an entity is [[ref:trustworthy]]. +The ToIP Trust Registry Query Protocol helps ecosystems create the foundation of trust within its governed domain, by providing a common protocol for querying information that helps the consuming party in deciding that an entity is [[ref: trustworthy]]. -The term [[ref:trust]] is loaded with varied meanings that often conflict. In the context of [[ref:trust registries]] we need to establish the scope of what we are talking about when we apply the term "trust" to trust registires. There are baseline definitions that follow this limiting scope. +In addition to providing information on its own ecosystem, the Trust Registry Query Protocol (TRQP) enables creation of a registry of registries. This is done by allowing an ecosystem to assert trust to other trust registries, and thus ecosystems. This can be achieved by allowing a governance entity to assert that consuming parties that rely on the trust registry, may also utilize information from another trust registry for additional assertions. This effectively creates transitive trust across ecosystems to achieve wider reach. -A trust registry does not create trust. The decision for one entity to "trust" another is their decision. A trust registry may provide information that helps the *consuming party* in deciding that an entity is [[ref: trustworthy]]. - -::: todo - define term "*consuming party*" - OR find better term and capture definition. - - -### Copyright Notice +The Trust Registry Query Protocol serves to provide a simple interface to enable querying of systems of record that provide the information that drives a trust registry. There are a plethora of systems that contain answers that are required to make trust decisions. The protocol is intended to make the communication with any particular system-of-record consistent and simple. +## Foreword This specification is subject to the **OWF Contributor License Agreement 1.0 - Copyright** available at [https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright). @@ -41,28 +27,11 @@ If source code is included in the specification, that code is subject to the Apa These terms are inherited from the Technical Stack Working Group at the Trust over IP Foundation. [Working Group Charter](https://trustoverip.org/wp-content/uploads/TSWG-2-Charter-Revision.pdf) - -### Terms of Use - -These materials are made available under and are subject to the [OWF CLA 1.0 - Copyright & Patent license](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owf-contributor-license-agreement-1-0-copyright-and-patent). Any source code is made available under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.txt). - THESE MATERIALS ARE PROVIDED “AS IS.” The Trust Over IP Foundation, established as the Joint Development Foundation Projects, LLC, Trust Over IP Foundation Series ("ToIP"), and its members and contributors (each of ToIP, its members and contributors, a "ToIP Party") expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL ANY ToIP PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THESE MATERIALS, ANY DELIVERABLE OR THE ToIP GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -### Introduction - -*This section is non-normative* - -A [[ref: trust registry]] is a resource that helps to bind governance (business, legal, and social mandates) for an ecosystem. A trust registry helps get the main answers that parties inside and outside of the ecosystem need to tie the governance into their own systems - both technically (it is a protocol) and on a governance (the information provided is created via a governed process). - -It is crucially important to understand that a trust registry does not create trust, nor the conditions for trust, by itself. Trust and belief in the data provided by a trust registry is an outcome of governance. - -We need answers to a simple question: - -> Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`? + +### Conventions +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" 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. -[[def: trustworthiness]] -~ An attribute of a person or organization that provides confidence to others of the qualifications, capabilities, and reliability of that entity to perform specific tasks and fulfill assigned responsibilities. Trustworthiness is also a characteristic of information technology products and systems (see Section 2.6.2 on trustworthiness of information systems). The attribute of trustworthiness, whether applied to people, processes, or technologies, can be measured, at least in relative terms if not quantitatively.48 The determination of trustworthiness plays a key role in establishing trust relationships among persons and organizations. The trust relationships are key factors in risk decisions made by senior leaders/executives. NOTE: Current state-of-the-practice for measuring trustworthiness can reliably differentiate between widely different levels of trustworthiness and is capable of producing a trustworthiness scale that is hierarchical between similar instances of measuring activities (e.g., the results from ISO/IEC 15408 [Common Criteria] evaluations). -- source: [NIST Special Publication 800-39](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-39.pdf) p.24 diff --git a/spec/introduction.md b/spec/introduction.md index eded113..c54bf44 100644 --- a/spec/introduction.md +++ b/spec/introduction.md @@ -1,14 +1,67 @@ [//]: # (Pandoc Formatting Macros) -[//]: # (::: introtitle) +[//]: # (\mainmatter) -[//]: # (Introduction) - -[//]: # (:::) +[//]: # (\doctitle) ## Introduction +*This section is non-normative* + +A [[ref: trust registry]] is a resource that helps to bind governance (business, legal, and social mandates) for an ecosystem. A trust registry helps get the main answers that parties inside and outside of the ecosystem need to tie the governance into their own systems - both technically and on a governance (the information provided is created via a governed process). + +It is crucially important to understand that a trust registry does not create trust, nor the conditions for trust, by itself. Trust and belief in the data provided by a trust registry is an outcome of governance. + +We need answers to a simple question: + +> Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`? + +The Trust Registry Query Protocol (TRQP) serves to provide a simple interface to enable querying of systems of record that provide the information that drives a trust registry. There are a plethora of systems that contain answers that are required to make trust decisions. The protocol is intended to make the communication with any particular system-of-record consistent and simple. + +It is intentionally simple to allow rapid integration into external systems. + +The TRQP does not: + * create a trust registry - it allows (read-only) access to a system-of-record that has the data needed to generate answers that a trust registry provides. + * create new information - the Create, Update, and Delete of CRUD are not supported. Systems-of-record perform the full CRUD operations. The protocol provides a simple and consistent way of retrieving information from a system. + * create nor implement governance - the system-of-record that supports the TRQP may have technical ways of doing this, supported by manual operations. Regardless, the TRQP has no opinion on how governance is implemented - just that the information retrieved complies with the stated EGF. + * make decisions - the TRWP serves up data that are inputs to trust decisions. + * assign Roles or Rights, though a consuming system may take information that is received via the TRQP and assign these. + +It is most crucial to understand that a Trust Registry does NOT create authority. The authority of a trust registry is an outcome of governance. + +The purpose of this [[xref: TOIP, ToIP specification]] is to define a standard interoperable protocol for querying a global web of [[xref: TOIP, peer]] [[xref: TOIP, trust registries]], each of which can answer queries about whether a particular [[xref: TOIP, entity]] holds an [[ref:authorization]], in a particular [[xref: TOIP, digital trust ecosystem]] (defined under an [[xref: TOIP, EGF]]), as well as which peer trust registries acknowledge each other. + +### Trust Registry Query Protocol features +A core role within the ToIP stack is a [[xref: TOIP, trust registry]]. This is a network service that enables the [[xref:TOIP, governing authority]] for an [[xref: TOIP, EGF]] to share information about their ecosystem. In particular, which [[xref: TOIP, governed parties]] hold which [[ref: authorizations]] under the EGF. + +A trust registry query protocol thus should provide the following features: + +1. interface to query if a particular [[xref: TOIP, entity]] holds specific [[ref:authorization]] under a defined [[xref: TOIP, EGF]]? + - e.g. "Does entity X hold the authorization of `canada.driver.license.issue` under Canadian Driver's license scheme?" +2. interface to query what other trust registries are recognized by this trust registry? + +### Read-only query Protocol +The primary question (Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`) we need an answer to when working in an ecosystem is in itself a simple query. Furthermore, it is read-only query and it doesn't modify any information in a system of record. It just makes data available. + +In the web service world the TRQP is purely a GET protocol. + +Just as important it is to understand what the TRQP does NOT do. The TRQP does NOT: +* affect the operations and governance of the systems that support querying using the TRQP. +* create, update, or delete data in a system. In web services this means the TRQP does to PUT, POST, DELETE, and other non-GET operations. + +As with all layers of the [[xref: TOIP, ToIP stack]], the purpose of a [[xref: TOIP, ToIP specification]] is to enable the technical interoperability necessary to support transitive trust within and between different [[xref: TOIP, trust communities]] implementing the [[xref: TOIP, ToIP stack]]. In this case, the desired interoperability outcome is a common query protocol that works between any number of decentralized peer trust registries operated by independent governing authorities** representing multiple legal and business jurisdictions. + +### Registry of Registries +A Registry of Registries (RoR), is a form of [[xref: TOIP, trust registry]] that primarily serves information about other [[xref: TOIP, trust registries]]. + +1. What other [[xref: TOIP, governing authorities]] are known to the RoR. +2. Which [[xref: TOIP, trust registry]] are known to be authoritative for particular actions. Examples: + - Which trust registry is known to issue university diplomas for a particular jurisdiction? + - Which trust registry is known to manage a list of professionals (e.g. CPAs, lawyers, engineers) that have particular signing rights (authorizations)? +3. Which [[xref: TOIP, trust registry]] are known to operate under a given [[xref: TOIP, EGF]]. + +The results on a [[xref: TOIP, trust decision]] based on input from a trust registry may range from: +* immediate decision that the entity meets or cannot meet the full requirement of the [[ref:trust relationship]]; or +* further input is required before trust decision can be made. -::: todo -create introduction -::: +These decisions relate to a determination that a relationship is (or is not) sufficiently [[ref: trustworthy]] to establish a [[ref: trust relationship]]. To reach that determination, each party may have its own way of determining the [[ref: trustworthiness]] of their counterparty for the [[ref: trust relationship]] that they require. diff --git a/spec/requirements.md b/spec/requirements.md index 46c667c..b9975bc 100644 --- a/spec/requirements.md +++ b/spec/requirements.md @@ -112,56 +112,55 @@ Trust Over IP hosts a [Service Profile]() with the following pointer: By implementing service profiles, it enables easier interoperability and discovery of service capabilities for the trust registry being implemented. -### Trust Registry Protocol [TRP-*] +### Trust Registry Query Protocol [TRQP-*] -The authoritative technical specifications for the API calls in the ToIP Trust Registry Protocol V1 are specified in Appendix A (OpenAPI YAML file). This section contains a textual description of the **requirements**. +The authoritative technical specifications for the API calls in the ToIP Trust Registry Query Protocol are specified in Appendix A (OpenAPI YAML file). This section contains a textual description of the **requirements**. **Trust registries** implementing this protocol: -* [TRP-1] MUST maintain the service implementing this protocol at the HTTPS URI specified in the _[Trust Registry Service Property](#trust-registry-service-property)_ section. -* [TRP-2] The system SHOULD support queries that are at a point in time in the past. - * [TRP-2-1] The parameter for the point in time must be named `queryTime`. - * [TRP-2-2] The datetime value provided MUST be formatted per [[spec-norm:RFC3339]] using the UTC (i.e. Z for Zulu) zero offset (e.g. "2018-03-20T09:12:28Z". - * [TRP-2-3] If the system does not support non-current data, and the the `queryTime` parameter is present, the system MUST NOT return entity data and must se http error code 405 (Method not allowed). - -* [TRP-3] MUST return responses to queries for the **status value** of a **registry entry** that satisfies one or more of the following sets of query parameters: - - - [TRP-3-1] **Entity Authorization**: Given the `entityDID`, and `authorization` return the status of that registered entity, MUST return exactly one of the following **status values** for a **registry entry** satisfying the query parameters: - - `Not Found` + http code 404 - entry not found. - - `Current` + http code 200 - authorization for the registered entity is current as of the time of query, or as of the time requested. - - `Expired` + http code 200 - authorization has expired (e.g. not renewed after the previous valid registration period) - - `Terminated` + http code 200 - authorization was terminated (e.g. voluntary termination by the **registered entity**) - - `Revoked` + http code 200 - authorization was revoked (e.g. involuntary termination by the **governing authority**) - - [TRP-3-2] **Entity Authorizations**: Given only the `entityDID` the system SHOULD return the array of Authorization objects for the entity identified by `entityDID`. - - ii. [TRP-3-2] **Recognized Registry:** Given the entityDID the system SHOULD return the list of [[def:trust registries]] that the entity has indicated it is registered in. - - [TRP-3-2-1] The system MUST NOT return more than one trust registry in the array designated as a [[def: primary registry]]. +* [TRQP-1] MUST maintain the service implementing this protocol at the HTTPS URI specified in the _[Trust Registry Service Property](#trust-registry-service-property)_ section. +* [TRQP-2] The system SHOULD support queries that are at a point in time in the past. + - [TRQP-2-1] The parameter for the point in time must be named `queryTime`. + - [TRQP-2-2] The datetime value provided MUST be formatted per [[spec-norm:RFC3339]] using the UTC (i.e. Z for Zulu) zero offset (e.g. "2018-03-20T09:12:28Z". + - [TRQP-2-3] If the system does not support non-current data, and the the `queryTime` parameter is present, the system MUST NOT return entity data and must se http error code 405 (Method not allowed). + +* [TRQP-3] MUST return responses to queries for the **status value** of a **registry entry** that satisfies one or more of the following sets of query parameters: + - [TRQP-3-1] **Entity Authorization**: Given the `entityDID`, and `authorization` return the status of that registered entity, MUST return exactly one of the following **status values** for a **registry entry** satisfying the query parameters: + - `Not Found` + http code 404 - entry not found. + - `Current` + http code 200 - authorization for the registered entity is current as of the time of query, or as of the time requested. + - `Expired` + http code 200 - authorization has expired (e.g. not renewed after the previous valid registration period) + - `Terminated` + http code 200 - authorization was terminated (e.g. voluntary termination by the **registered entity**) + - `Revoked` + http code 200 - authorization was revoked (e.g. involuntary termination by the **governing authority**) + - [TRQP-3-2] **Entity Authorizations**: Given only the `entityDID` the system SHOULD return the array of Authorization objects for the entity identified by `entityDID`. + - [TRQP-3-3] **Recognized Registry:** Given the entityDID the system SHOULD return the list of [[def:trust registries]] that the entity has indicated it is registered in. + - [TRQP-3-3-1] The system MUST NOT return more than one trust registry in the array designated as a [[def: primary registry]]. ::: TODO: Align VID and/or DID terminology. ::: -[TRP-4] MUST return responses using the data model specified in the OpenAPI Specification . - -[TRP-5] For queries returning a **status value** other than `Not Found`, the response MUST return the following values: - - [TRP-5-1] The system must return the parameter values exactly as supplied in the query (so responses can be stateless). - - [TRP-5-2] The system must return the **status value** for the entity (per TRP-3-1). - - [TRP-5-3] The system must return exactly two **datetime values** conforming to the following requirements: - - [TRP-5-3-1]The value labels MUST be: - - i. `AuthorizationStartDate` - - ii. `AuthorizationEndDate` - - [TRP-5-3-2] The datetime values MUST be formatted to comply with [[spec-norm:RFC3339]] in the UTC/Z time zone with no offset. - - [TRP-5-3-3] The `AuthorizationStartDate` MUST be the date that the **registered entity** authorization began. - - [TRP-5-3-4] The `AuthorizationEndDate` MUST be either: - - [TRP-5-3-4-1] `Null` for an entry whose **status value** is `Current` at the time of the query. - - [TRP-5-3-4-2] A specific datetime value if the **registered entity** **status value** is `Expired`, `Terminated` or `Revoked.` - - [TRP-5-3-5] If a **registered entity** has multiple entries in the system (representing an authorization history), the value that is active at the time indicated must be returned: - - [TRP-5-3-5-1] when no `queryTime` value is provided the value that is active at time of the query MUST be returned. - - [TRP-5-3-5-2] when a `queryTime` parameter is provided the entry that is active at that time (i.e. indicted by `queryTime`) MUST be returned. +* [TRQP-4] MUST return responses using the data model specified in the OpenAPI Specification . + +* [TRQP-5] For queries returning a **status value** other than `Not Found`, the response MUST return the following values: + - [TRQP-5-1] The system must return the parameter values exactly as supplied in the query (so responses can be stateless). + - [TRQP-5-2] The system must return the **status value** for the entity (per TRP-3-1). + - [TRQP-5-3] The system must return exactly two **datetime values** conforming to the following requirements: + - [TRQP-5-3-1]The value labels MUST be: + - i. `AuthorizationStartDate` + - ii. `AuthorizationEndDate` + - [TRQP-5-3-2] The datetime values MUST be formatted to comply with [[spec-norm:RFC3339]] in the UTC/Z time zone with no offset. + - [TRQP-5-3-3] The `AuthorizationStartDate` MUST be the date that the **registered entity** authorization began. + - [TRQP-5-3-4] The `AuthorizationEndDate` MUST be either: + - [TRQP-5-3-4-1] `Null` for an entry whose **status value** is `Current` at the time of the query. + - [TRQP-5-3-4-2] A specific datetime value if the **registered entity** **status value** is `Expired`, `Terminated` or `Revoked`. + - [TRQP-5-3-5] If a **registered entity** has multiple entries in the system (representing an authorization history), the value that is active at the time indicated must be returned: + - [TRQP-5-3-5-1] when no `queryTime` value is provided the value that is active at time of the query MUST be returned. + - [TRQP-5-3-5-2] when a `queryTime` parameter is provided the entry that is active at that time (i.e. indicted by `queryTime`) MUST be returned. ### Anti-Requirements -The following are considered anti-requirements in that they have been considered in the current design of the TRP: +The following are considered anti-requirements in that they have been considered in the current design of the TRQP: * [AR-1] SHALL NOT support query operations for the history of a [[ref: registered entity]]. @@ -169,6 +168,6 @@ The following are considered anti-requirements in that they have been considered * [AR-3]]SHALL NOT support automated rules processing in the protocol. A rules engine can certainly use the protocol. -* [AR-4] Anything other than read-only operations. The TRP is a read-only (RETRIEVE in the CRUD sense) protocol. +* [AR-4] Anything other than read-only operations. The TRQP is a read-only (RETRIEVE in the CRUD sense) protocol. diff --git a/spec/revision_history.md b/spec/revision_history.md index a845266..1786737 100644 --- a/spec/revision_history.md +++ b/spec/revision_history.md @@ -4,3 +4,7 @@ [[This section applies after the specification has been released for a Public Review, including Implementers Public Review]]. ::: +* 2024-06-24 + - changed specification name to add "Query" to the title + - updated beidge diagram to reflect profile need for OIDF + - fixed Swagger links \ No newline at end of file diff --git a/spec/scope.md b/spec/scope.md deleted file mode 100644 index c90d8f0..0000000 --- a/spec/scope.md +++ /dev/null @@ -1,107 +0,0 @@ - -[//]: # (Pandoc Formatting Macros) - -[//]: # (\mainmatter) - -[//]: # (\doctitle) - -## Scope - -The Trust Registry Protocol (TRP) serves to provide a simple interface to enable querying of systems of record that provide the information that drives a trust registry. There are a plethora of systems that contain answers that are required to make trust decisions. The protocol is intended to make the communication with any particular system-of-record consistent and simple. - -It is intentionally simple to allow rapid integration into external systems. - -The TRP does not: - * create a trust registry - it allows (read-only) access to a system-of-record that has the data needed to generate answers that a trust registry provides. - * create new information - the Create, Update, and Delete of CRUD are not supported. Systems-of-record perform the full CRUD operations. The protocol provides a simple and consistent way of retrieving information from a system. - * create nor implement governance - the system-of-record that supports the TRP may have technical ways of doing this, supported by manual operations. Regardless, the TRP has no opinion on how governance is implemented - just that the information retrieved complies with the stated EGF. - * make decisions - the TRP serves up data that are inputs to trust decisions. - * assign Roles or Rights, though a consuming system may take information that is received via the TRP and assign these. - -It is most crucial to understand that a Trust Registry does NOT create authority. As Jacques Latour says "the authority of a trust registry is an outcome of governance". - -### Purpose - -The purpose of this [[xref: TOIP, ToIP specification]] is to define a standard interoperable protocol for querying a global web of [[xref: TOIP, peer]] [[xref: TOIP, trust registries]], each of which can answer queries about whether a particular [[xref: TOIP, entity]] holds an [[ref:authorization]], in a particular [[xref: TOIP, digital trust ecosystem]] (defined under an [[xref: TOIP, EGF]]), as well as which peer trust registries acknowledge each other. - -The Trust Registry Protocol enables an interested party to ask the following question: - -> Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`? - - - - -### Motivations - -A core role within the ToIP stack is a [[xref: TOIP, trust registry]]. This is a network service that enables the [[xref:TOIP, governing authority]] for an [[xref: TOIP, EGF]] to share information about their ecosystem. In particular, which [[xref: TOIP, governed parties]] hold which [[ref: authorizations]] under the EGF. For example: - -1. Does a particular [[xref: TOIP, entity]] hold a particular [[ref:authorization]] under an EGF? - - e.g. "Does entity X hold the authorization of `canada.driver.license.issue` under an EGF? - notionaly equating to the authority to "issue" a "driver license in Canada"; -2. What other trust registries are recognized by this trust registry? - -The Trust Registry Protocol is focused on answering those questions. - - -### Querying Consistently Requires a (Read-Only) Protocol - -One primary question we need an answer to when working in an ecosystem is (as stated throughout this specification): - -> Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`? - - -This is a query - a simple one. Further, it is read-only. It doesn't modify any information in a system of record. It just makes data available. - -In the web service world the TRP is purely a GET protocol. - -Just as important, is to understand what the Trust Registry Protocol does NOT do. The TRP does NOT: - -* affect the operations and governance of the systems that support querying using the TRP. -* create, update, or delete data in a system. In web services this means the TRP does to PUT, POST, DELETE, and other non-GET operations. - -### Querying a Trust Registry - -As with all layers of the [[xref: TOIP, ToIP stack]], the purpose of a [[xref: TOIP, ToIP specification]] is to enable the technical interoperability necessary to support transitive trust within and between different [[xref: TOIP, trust communities]] implementing the [[xref: TOIP, ToIP stack]]. In this case, the desired interoperability outcome is a common query protocol that works between any number of decentralized peer trust registries operated by independent governing authorities** representing multiple legal and business jurisdictions. - -### Registry of Registry (MetaRegistry) - -A Registry of Registries (RoR), is a form of [[xref: TOIP, trust registry]] that primarily serves information about other [[xref: TOIP, trust registries]]. - -1. What other [[xref: TOIP, governing authorities]] are known to the RoR. -2. Which [[xref: TOIP, trust registry]] are known to be authoritative for particular actions. Examples: - - Which trust registry is known to issue university diplomas for a particular jurisdiction? - - Which trust registry is known to manage a list of professionals (e.g. CPAs, lawyers, engineers) that have particular signing rights (authorizations)? -3. Which [[xref: TOIP, trust registry]] are known to operate under a given [[xref: TOIP, EGF]]. - - -### On Trust, Trustworthy, and Trustworthiness - -The term [[ref:trust]] is loaded with varied meanings that often conflict. In the context of [[ref:trust registries]] we need to establish the scope of what we are talking about when we apply the term "trust" to trust registires. There are baseline definitions that follow this limiting scope. - -A trust registry does not create trust. The decision for one entity to "trust" another is their decision. A trust registry may provide information that helps the *consuming party* in deciding that an entity is [[ref: trustworthy]]. - -::: todo - define term "*consuming party*" - OR find better term and capture definition. -::: - -The results on a [[xref: TOIP, trust decision]] based on input from a trust registry may range from: -* immediate decision that the entity meets or cannot meet the full requirement of the [[ref:trust relationship]]; or -* further input is required before trust decision can be made. - -These decisions relate to a determination that a relationship is (or is not) sufficiently [[ref: trustworthy]] to establish a [[ref: trust relationship]]. To reach that determination, each party may have its own way of determining the [[ref: trustworthiness]] of their counterparty for the [[ref: trust relationship]] that they require. - -The following terms are presented to help create a general understanding and may be only indirectly related to trust registry efforts: - -[[def: trust]] -~ A belief that an entity will behave in a predictable manner in specified circumstances. The entity may be a person, process, object or any combination of such components. The entity can be of any size from a single hardware component or software module, to a piece of equipment identified by make and model, to a site or location, to an organization, to a nation-state. Trust, while inherently a subjective determination, can be based on objective evidence and subjective elements. The objective grounds for trust can include for example, the results of information technology product testing and evaluation. Subjective belief, level of comfort, and experience may supplement (or even replace) objective evidence, or substitute for such evidence when it is unavailable. Trust is usually relative to a specific circumstance or situation (e.g., the amount of money involved in a transaction, the sensitivity or criticality of information, or whether safety is an issue with human lives at stake). Trust is generally not transitive (e.g., you trust a friend but not necessarily a friend of a friend). Finally, trust is generally earned, based on experience or measurement. -- source: [NIST Special Publication 800-39](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-39.pdf) p.24 - -[[def: trust relationship]] -~ An agreed upon relationship between two or more system elements that is governed by criteria for secure interaction, behavior, and outcomes relative to the protection of assets. -- source: [NIST SP 800-160v1r1](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-160v1r1.pdf) - -[[def: trustworthy]] -~ Worthy of the confidence to others of the qualifications, capabilities, and reliability of that entity to perform specific tasks and fulfill assigned responsibilities. (note: based on the definition of [[ref: trustworthiness]]. note: from source "This refers to trust relationships between system elements implemented by hardware, firmware, and software" but the definition largely works. - -[[def: trustworthiness]] -~ An attribute of a person or organization that provides confidence to others of the qualifications, capabilities, and reliability of that entity to perform specific tasks and fulfill assigned responsibilities. Trustworthiness is also a characteristic of information technology products and systems (see Section 2.6.2 on trustworthiness of information systems). The attribute of trustworthiness, whether applied to people, processes, or technologies, can be measured, at least in relative terms if not quantitatively.48 The determination of trustworthiness plays a key role in establishing trust relationships among persons and organizations. The trust relationships are key factors in risk decisions made by senior leaders/executives. NOTE: Current state-of-the-practice for measuring trustworthiness can reliably differentiate between widely different levels of trustworthiness and is capable of producing a trustworthiness scale that is hierarchical between similar instances of measuring activities (e.g., the results from ISO/IEC 15408 [Common Criteria] evaluations). -- source: [NIST Special Publication 800-39](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-39.pdf) p.24 diff --git a/spec/terms_and_definitions.md b/spec/terms_and_definitions.md index a1f5ed2..9d8a956 100644 --- a/spec/terms_and_definitions.md +++ b/spec/terms_and_definitions.md @@ -8,34 +8,30 @@ [//]: # (: file format defined by ISO 32000-2) ## Terms & Definitions - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [[spec-inform:RFC2119]] when, and only when, they appear in all capitals, as shown here. +The following terms are used to describe concepts in this specification. [[def: authorization, authorizations]]: -~ Access privileges granted to an entity; conveys an “official” sanction to perform a cryptographic function or other sensitive activity. -* source: [NIST](https://csrc.nist.gov/glossary/term/permission) NIST SP 800-57 Part 2 Rev.1 under Authorization +~ Access privileges granted to an entity; conveys an “official” sanction to perform a cryptographic function or other sensitive activity. (Source: [NIST](https://csrc.nist.gov/glossary/term/permission) NIST SP 800-57 Part 2 Rev.1 under Authorization) + ::: issue https://github.com/trustoverip/tswg-trust-registry-protocol/issues/6 - May need a `governed authorization` term to help link tech+governance. ::: - [[def: authorized trust registry, authorized trust registries]] ~ The primary trust registry plus all secondary trust registries are collectively referred to as the authorized trust registries. - [[def: authorization namespace]]: ~ A well-known string that is used in an EGF to indicate a discrete authorization. Examples (non-exhaustive): "canada:driver-license", "eu:trusted-list.authorized-timestamp", "global:tsm" +[[def: consuming party, consuming parties]]: +~ A party that consumes the services and information provided by a [[xref: TOIP, trust registry]] in order to make a trust decision. [[def: registered entity, registered entities]]: ~ An [[xref: TOIP, entity]] that is listed in the system (i.e. the [[xref: TOIP, trust registry]]) that is being queried. - [[def: permission]]: -~ Authorization to perform some action on a system. - -* Source: [NIST](https://csrc.nist.gov/glossary/term/permission) +~ Authorization to perform some action on a system. (Source: [NIST](https://csrc.nist.gov/glossary/term/permission)) [[def: primary trust registry]]: ~ The single [[xref: TOIP, trust registry]] that is considered the primary source for information of a particular type in an ecosystem. @@ -44,23 +40,31 @@ https://github.com/trustoverip/tswg-trust-registry-protocol/issues/6 ~ A trust registry that has copies of information based on the ecosystem's [[def:primary trust registry]]. [[def: service endpoint]]: -~ A network address, such as an HTTP URL, at which services operate on behalf of a DID subject. - -~ Source: [[spec-norm:DID-CORE]] +~ A network address, such as an HTTP URL, at which services operate on behalf of a DID subject. (Source: [[spec-norm:DID-CORE]]) [[def: service property]]: -* in context of: [TRP-1] ...MUST publish, in the [[xref: TOIP, DID document]] associated with the **DID** identifying its **EGF**, a [[ref: service property]] specifying the [[ref: service endpoint]] - +~ in context of: [TRQP-1] ...MUST publish, in the [[xref: TOIP, DID document]] associated with the **DID** identifying its **EGF**, a [[ref: service property]] specifying the [[ref: service endpoint]] [[def: trust registry, trust registries]]: -~ A registry that serves as an authoritative source for trust graphs or other governed information describing one or more trust communities. A trust registry is typically authorized by a governance framework. -* See also: [[xref: TOIP, trust list]] +~ A registry that serves as an authoritative source for trust graphs or other governed information describing one or more trust communities. A trust registry is typically authorized by a governance framework. (See also: [[xref: TOIP, trust list]]) + +[[def: trust]] +~ A belief that an entity will behave in a predictable manner in specified circumstances. The entity may be a person, process, object or any combination of such components. The entity can be of any size from a single hardware component or software module, to a piece of equipment identified by make and model, to a site or location, to an organization, to a nation-state. Trust, while inherently a subjective determination, can be based on objective evidence and subjective elements. The objective grounds for trust can include for example, the results of information technology product testing and evaluation. Subjective belief, level of comfort, and experience may supplement (or even replace) objective evidence, or substitute for such evidence when it is unavailable. Trust is usually relative to a specific circumstance or situation (e.g., the amount of money involved in a transaction, the sensitivity or criticality of information, or whether safety is an issue with human lives at stake). Trust is generally not transitive (e.g., you trust a friend but not necessarily a friend of a friend). Finally, trust is generally earned, based on experience or measurement. (source: [NIST Special Publication 800-39](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-39.pdf) p.24) + +[[def: trust relationship]] +~ An agreed upon relationship between two or more system elements that is governed by criteria for secure interaction, behavior, and outcomes relative to the protection of assets. (source: [NIST SP 800-160v1r1](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-160v1r1.pdf)) + +[[def: trustworthy]] +~ Worthy of the confidence to others of the qualifications, capabilities, and reliability of that entity to perform specific tasks and fulfill assigned responsibilities. (note: based on the definition of [[ref: trustworthiness]]. note: from source "This refers to trust relationships between system elements implemented by hardware, firmware, and software" but the definition largely works. + +[[def: trustworthiness]] +~ An attribute of a person or organization that provides confidence to others of the qualifications, capabilities, and reliability of that entity to perform specific tasks and fulfill assigned responsibilities. Trustworthiness is also a characteristic of information technology products and systems (see Section 2.6.2 on trustworthiness of information systems). The attribute of trustworthiness, whether applied to people, processes, or technologies, can be measured, at least in relative terms if not quantitatively.48 The determination of trustworthiness plays a key role in establishing trust relationships among persons and organizations. The trust relationships are key factors in risk decisions made by senior leaders/executives. NOTE: Current state-of-the-practice for measuring trustworthiness can reliably differentiate between widely different levels of trustworthiness and is capable of producing a trustworthiness scale that is hierarchical between similar instances of measuring activities (e.g., the results from ISO/IEC 15408 [Common Criteria] evaluations). (source: [NIST Special Publication 800-39](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-39.pdf) p.24) [[def: trusted party]]: -~ A party that is trusted by an entity to faithfully perform certain services for that entity. An entity may choose to act as a trusted party for itself. -- source: [NIST SP 800-56B Rev. 2](https://doi.org/10.6028/NIST.SP.800-56Br2) under Trusted party +~ A party that is trusted by an entity to faithfully perform certain services for that entity. An entity may choose to act as a trusted party for itself.(source: [NIST SP 800-56B Rev. 2](https://doi.org/10.6028/NIST.SP.800-56Br2) under Trusted party) [[def: VID Type, VID Types]]: ~ A specific kind of [[xref: TOIP, VID]]. + diff --git a/spec/title.md b/spec/title.md index b9264b7..c7f434e 100644 --- a/spec/title.md +++ b/spec/title.md @@ -1,5 +1,4 @@ -ToIP Trust Registry Protocol version 1.0 Specification -================== +ToIP Trust Registry Query Protocol v1.0 Specification **Specification Status**: v1.0 Implementers Draft diff --git a/specs.json b/specs.json index 8ee5e21..aa8e554 100644 --- a/specs.json +++ b/specs.json @@ -1,7 +1,7 @@ { "specs": [ { - "title": "ToIP Trust Registry Protocol v2 TF DRAFT", + "title": "ToIP Trust Query Registry Protocol v2 TF DRAFT", "spec_directory": "./spec", "output_path": "./docs", "markdown_paths": [ @@ -10,10 +10,10 @@ "revision_history.md", "toc.md", "foreword.md", - "scope.md", - "normative_references.md", "terms_and_definitions.md", + "introduction.md", "requirements.md", + "normative_references.md", "clauses.md", "annex.md", "biblio.md"