Skip to content

Commit

Permalink
Merge pull request #23 from darrellodonnell/main
Browse files Browse the repository at this point in the history
Prepping for IR
  • Loading branch information
darrellodonnell authored Mar 28, 2024
2 parents c1c31a4 + 0090d68 commit 84470f6
Showing 12 changed files with 182 additions and 139 deletions.
67 changes: 45 additions & 22 deletions api/toip-tswg-trustregistryprotocol-v2.yaml
Original file line number Diff line number Diff line change
@@ -13,8 +13,8 @@ info:
* Listing Registries that are known (to the registry being queried).
* list the acknowledged trust registries that the RoR recognizes and what
that may mean in the context of a particular governance framework.
version: 2.0.alpha
title: ToIP Trust Registry Protocol v2 - Working Draft
version: 2.0.0
title: ToIP Trust Registry (Query) Protocol v2 - Working Draft
contact:
email: [email protected]
license:
@@ -379,7 +379,7 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataType'
$ref: '#/components/schemas/RegistryMetadataType'
'400':
$ref: '#/components/responses/BadRequest'
'401':
@@ -749,6 +749,37 @@ components:
description: URI of the EGF that defines the namespace.
description:
type: string
RegistryMetadataType:
type: object
required:
- lastupdated
properties:
lastupdated:
type: string
format: date-time
primaryEGFURI:
type: string
example:
- "did:example:GlobalDriverLicenseDID"
description: URI of the EGF that governs the Trust Registry.
additionalEGFURIs:
type: array
description: "List of URIs of Ecosystem Governance Frameworks that this Trust Registry operates under, in addition to the .primaryEGFURI"
items:
$ref: '#/components/schemas/Uri'
participatingNamepaces:
$ref: '#/components/schemas/NamespaceListType'
languages:
type: array
description: >-
language codes (RFC 4646 -
https://datatracker.ietf.org/doc/html/rfc4646)
items:
type: string
examples:
- "en"
- "en-CA"
- "fr-CA"
RegistryType:
type: object
description: >
@@ -771,6 +802,16 @@ components:
type: string
examples:
- "Established on June 14, 1922, Professional Engineers Ontario (PEO) is the licensing and regulating body for professional engineering in the province."
primaryEGFURI:
type: string
example:
- "did:example:GlobalDriverLicenseDID"
description: URI of the EGF that governs the Trust Registry.
additionalEGFURIs:
type: array
description: "List of URIs of Ecosystem Governance Frameworks that this Trust Registry operates under, in addition to the .primaryEGFURI"
items:
$ref: '#/components/schemas/Uri'
participatingNamepaces:
$ref: '#/components/schemas/NamespaceListType'
peerType:
@@ -850,25 +891,7 @@ components:
type: array
items:
$ref: '#/components/schemas/VIDMethodType'
MetadataType:
type: object
required:
- lastupdated
properties:
lastupdated:
type: string
format: date-time
languages:
type: array
description: >-
language codes (RFC 4646 -
https://datatracker.ietf.org/doc/html/rfc4646)
items:
type: string
examples:
- "en"
- "en-CA"
- "fr-CA"

ExportLookups:
type: object
properties:
6 changes: 4 additions & 2 deletions diagrams/highlevel.plantuml
Original file line number Diff line number Diff line change
@@ -45,13 +45,15 @@ class Lookup {
}

class Metadata {
EGFURI: URI ' (duplicated above)
class RegistryMetadata {
primaryEGFURI: URI ' (duplicated above)
additionalEGFURI[]
TrustRegistryName: string
RawAPIEndpoint: URL
' AuthorityClaim: string
lastUpdated: datetime
namespaces: string[]
supportedLanguages[]

' Languages()
14 changes: 7 additions & 7 deletions docs/api/redoc-static.html

Large diffs are not rendered by default.

50 changes: 22 additions & 28 deletions spec/foreword.md
Original file line number Diff line number Diff line change
@@ -10,45 +10,39 @@

## Foreword

ToIP (Trust Over IP Foundation) create a _____
::: todo
Create Foreword content in advance of Public Review Draft (i.e. no content expected for Implementers Review Draft)
:::

* TODO: Preamble along the lines of an ISO Foreword.

List significant changes (non-normative):
### Copyright Notice

* 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.
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).

### On Trust, Trustworthy, and Trustworthiness
If source code is included in the specification, that code is subject to the Apache 2.0 license unless otherwise marked. In the case of any conflict or confusion within this specification between the OWF Contributor License and the designated source code license, the terms of the OWF Contributor License shall apply.

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.
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)

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.
:::
### 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

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.
*This section is non-normative*

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.
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).

The following terms are presented to help create a general understanding and may be only indirectly related to trust registry efforts:
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.

[[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
We need answers to a simple question:

[[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)
> Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`?
[[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
58 changes: 15 additions & 43 deletions spec/header.md
Original file line number Diff line number Diff line change
@@ -7,49 +7,45 @@

[//]: # (:::)


### Document Status

Category | Status
**Category** | **Status**
:--- | :--------------
[Document Type](https://wiki.trustoverip.org/display/HOME/ToIP+Deliverable+Types%2C+Stages%2C+and+Processes) | Specification
Document Status | Draft
Document Purpose | Working Draft
[**Document Type**](https://wiki.trustoverip.org/display/HOME/ToIP+Deliverable+Types%2C+Stages%2C+and+Processes) | *Specification*
**Document Status** | *Draft*
**Document Purpose** | *Working Draft*

::: TODO:
::: todo
Shift `Document Purpose` to Implementer Review Draft before going to Implementer Review.
:::


## Draft Specification

### Note to Implementers and Reviewers
**Note to Implementers and Reviewers**

The intent of this Implementers Review Draft Deliverable is to drive input for the specification. Comments
The intent of this Implementers Review Draft Deliverable is to drive input for the specification. Comments are appreciated and encouraged. During the Implementers Review period (TODO: list dates) feedback may be dispositioned rapidly.

Provide input via:
* [GitHub Issues](https://github.com/trustoverip/tswg-trust-registry-protocol/issues) - for items that need to be tracked. These will be formally dispositioned.
* [GitHub Discussions](https://github.com/trustoverip/tswg-trust-registry-protocol/discussions) -
* [GitHub Discussions](https://github.com/trustoverip/tswg-trust-registry-protocol/discussions) - for items that are more discussion level.

::: TODO:
::: todo
TODO: complete this preamble. @darrellodonnell
:::

### Source
**Source/Resources:**

The following links will be helpful for editors and reviewers during the DRAFT stage.

* Source Code - [https://github.com/trustoverip/tswg-trust-registry-protocol](https://github.com/trustoverip/tswg-trust-registry-protocol)
* Rendered Specification (github.io Pages) - [https://trustoverip.github.io/tswg-trust-registry-protocol/](https://trustoverip.github.io/tswg-trust-registry-protocol/)
* Browseable (SwaggerHub) API - [https://app.swaggerhub.com/apis/continuumloop/trust-over_ip_trust_registry_protocol_res_tful_api_v_2/2.0.alpha-oas3.1](https://app.swaggerhub.com/apis/continuumloop/trust-over_ip_trust_registry_protocol_res_tful_api_v_2/2.0.alpha-oas3.1) - note there is no endpoint responding.
* Browseable (SwaggerHub) API - [https://app.swaggerhub.com/apis-docs/continuumloop/trust-over_ip_trust_registry_protocol_res_tful_api_v_2/2.0.0](https://app.swaggerhub.com/apis-docs/continuumloop/trust-over_ip_trust_registry_protocol_res_tful_api_v_2/2.0.0) - note there is no endpoint responding.
* Inline (Redocs) API Browser - [Redoc Rendering (static HTML) of specification](./api/redoc-static.html)


### Editors
**Editors:**

- [Darrell O'Donnell](https://github.com/darrellodonnell), [Continuum Loop Inc.](https://continuumloop.com/)

### Contributors
**Contributors:**

To comply with the intellectual property rights protections in[ the charter of the ToIP Foundation](https://docs.google.com/document/d/1hJ4YWH_efrYTRvzRI1N9YHwhUOyI_ScrPmI1D9T4_oc/edit?usp=sharing) (as required by all Joint Development Foundation projects hosted by the Linux Foundation), all contributors in any capacity to this Draft Deliverable MUST be current members of the ToIP Foundation. The following contributors each certify that they meet this requirement:

@@ -60,35 +56,11 @@ To comply with the intellectual property rights protections in[ the charter of t

-

### Participate
**[[SECTION will be removed before going to Review]]**
**Participate **

Participation is welcome.
Participation is welcomed and encouraged.

* [GitHub repo](https://github.com/trustoverip/tswg-trust-registry-protocol)
* [Trust Registry Task Force](https://wiki.trustoverip.org/display/HOME/Trust+Registry+Task+Force)
* [Commit history](https://github.com/trustoverip/tswg-trust-registry-protocol/commits/main)

------------------------------------
This document contains a specification for the ToIP Trust Registry Protocol.

Information about the current status of this document, any errata, and how to provide feedback on it, may be obtained at
[https://github.com/trustoverip/tswg-trust-registry-protocol](https://github.com/trustoverip/tswg-trust-registry-protocol).

### Copyright Notice

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).

If source code is included in the specification, that code is subject to the Apache 2.0 license unless otherwise marked. In the case of any conflict or confusion within this specification between the OWF Contributor License and the designated source code license, the terms of the OWF Contributor License shall apply.

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.
12 changes: 0 additions & 12 deletions spec/introduction.md

This file was deleted.

Loading

0 comments on commit 84470f6

Please sign in to comment.