§ ToIP Trust Registry Protocol version 2.0 Specification

Specification Status: v2.0 Implementers Draft

Category Status
Document Type Specification
Document Status Draft
Document Purpose Implementers Draft

Note to Implementers and Reviewers

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 (2024-04-03 to 2024-06-03) feedback may be dispositioned rapidly.

Provide input via:

This protocol is currently focused on read-only operations.

Source/Resources:

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

Editors:

Contributors:

To comply with the intellectual property rights protections in the charter of the ToIP Foundation (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:

§ Participate

WARNING

SECTION will be removed before going to Review]

Participation is welcomed and encouraged.

Revision History

NOTE

[[This section applies after the specification has been released for a Public Review, including Implementers Public Review]].

::: ISSUE Pandoc TOC not rendering :::

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

The term 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.

A trust registry may provide information that helps the consuming party in deciding that an entity is trustworthy. The ToIP Trust Registry 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 trustworthy.

In addition to providing information on its own ecosystem, the Trust Registry Protocol (TRP) 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.

The Trust Registry 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.

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

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.

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

§ Terms & Definitions

The following terms are used to describe concepts in this specification.

authorization:
Access privileges granted to an entity; conveys an “official” sanction to perform a cryptographic function or other sensitive activity. (Source: NIST 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.
authorized trust registry
The primary trust registry plus all secondary trust registries are collectively referred to as the authorized trust registries.
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”
consuming party:
A party that consumes the services and information provided by a trust registry in order to make a trust decision.
registered entity:
An entity that is listed in the system (i.e. the trust registry) that is being queried.
permission:
Authorization to perform some action on a system. (Source: NIST)
primary trust registry:
The single trust registry that is considered the primary source for information of a particular type in an ecosystem.
secondary trust registry:
A trust registry that has copies of information based on the ecosystem’s primary trust registry.
service endpoint:
A network address, such as an HTTP URL, at which services operate on behalf of a DID subject. (Source: [DID-CORE])
service property:
in context of: [TRP-1] …MUST publish, in the DID document associated with the DID identifying its EGF, a service property specifying the service endpoint
trust registry:
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: trust list)
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 p.24)
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)
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 trustworthiness. note: from source “This refers to trust relationships between system elements implemented by hardware, firmware, and software” but the definition largely works.
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 p.24)
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 under Trusted party)
VID Type:
A specific kind of VID.

§ Introduction

This section is non-normative

A 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 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:

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 ToIP specification is to define a standard interoperable protocol for querying a global web of peer trust registries, each of which can answer queries about whether a particular entity holds an authorization, in a particular digital trust ecosystem (defined under an EGF), as well as which peer trust registries acknowledge each other.

§ Trust Registry Protocol features

A core role within the ToIP stack is a trust registry. This is a network service that enables the governing authority for an EGF to share information about their ecosystem. In particular, which governed parties hold which authorizations under the EGF.

A trust registry protocol thus should provide the following features:

  1. interface to query if a particular entity holds specific authorization under a defined EGF?
  1. 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 TRP is purely a GET protocol.

Just as important it is to understand what the Trust Registry Protocol does NOT do. The TRP does NOT:

As with all layers of the ToIP stack, the purpose of a ToIP specification is to enable the technical interoperability necessary to support transitive trust within and between different trust communities implementing the 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 trust registry that primarily serves information about other trust registries.

  1. What other governing authorities are known to the RoR.
  2. Which trust registry are known to be authoritative for particular actions. Examples:
    • Which trust registry is known to issue university diplomas for a particular jurisdiction?
  1. Which trust registry are known to operate under a given EGF.

The results on a trust decision based on input from a trust registry may range from:

These decisions relate to a determination that a relationship is (or is not) sufficiently trustworthy to establish a trust relationship. To reach that determination, each party may have its own way of determining the trustworthiness of their counterparty for the trust relationship that they require.

§ Requirements

§ Registry Queries [RQ-*]

The following queries relate to receiving answers related to entities and other trust registries.

§ Configuration Queries [CQ-*]

The following queries relate to configuration of systems that will interact with the trust registry.

§ Metadata Queries [MQ-*]

  1. [MQ-2] SHOULD provide the legal name and jurisdiction of the governing authority for the trust registry service.
  2. [MQ-3] SHOULD provide the legal name and jurisdiction of the administering authority for the trust registry operator (if different from governing body).
  3. [MQ-4] SHOULD provide a textual description of the trust registry mandate.

§ Governing Authorities [GA-*]

Governing authorities compliant with this specification:

The primary trust registry plus all secondary trust registries are collectively referred to as the authorized trust registries.

§ Trust Registry Service Property [TRSP-*]

The DID document for the DID that identifies an EGF compliant with this specification MUST include a service property that meets the requirements in section 5.4 of [DID-CORE] plus the following additional requirements:

TODO

FIX

Registered entities MUST indicate which registries they are part of.

§ Service Profile Recommendation

the following recommendation is non-normative

It is recommended that the service leverage the Service Profile Specification. Trust Over IP hosts a Service Profile with the following pointer:

{
  "integrity": "<>",
  "profile": "<>"
  "uri": "<your service endpoint uri here>"
}

By implementing service profiles, it enables easier interoperability and discovery of service capabilities for the trust registry being implemented.

§ Trust Registry Protocol [TRP-*]

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.

Trust registries implementing this protocol:

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

§ Anti-Requirements

The following are considered anti-requirements in that they have been considered in the current design of the TRP:

§ Normative References

DID-CORE
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.
RFC3339
Date and Time on the Internet: Timestamps. G. Klyne; C. Newman; 2002-07. Status: Proposed Standard.

§ Non-Normative/Informative References

[[spec-inform]]

§ Annex A: Consolidated Requirements

For ease of reference, the following table consolidates all normative requirements in this specification. Each requirement is linked to the section in which it appears.

THE FOLLOWING REQUIREMENTS IN THE TABLE ARE JUST EXAMPLES FOR NOW.

TODO: Finalize table once requirements (earlier).

Req # Description Section
Governing Authority Requirements
GA-1 EGF MUST have exactly one primary trust registry. [#governing-authorities-ga-]
GA-2 EGF MAY have one or more secondary trust registries. [[#governing-authorities-ga-]
A.3 MUST publish an EGF that meets the requirements in:
A.3.1 This specification. [LINK]
A.3.2 The ToIP Governance Architecture Specification. Note that this includes the requirement that the EGF and all governed parties (which includes authorized issuers and authorized verifiers) [LINK]

§ Annex B: OpenAPI Specification

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.

There are several renderings of the OAS specification:

§ Annex C - Uses and Data Model Reference

§ Use of the Trust Registry Protocol.

The TRP is intended to be used in at least two key ways:

C4 Systems Model - showing native TRP support on one system, bridged support to two other systems (e.g. TRAIN and EU Trusted List ARF).

§ Object Model

We provide a high-level object model (NOTE: source of truth is the Swagger as this diagram may be out of date during development)

High Level Object Model

§ Annex D - Guides (for future breakout)

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:

✕
Table of Contents ✕
anonymous
An adjective describing when the identity of a natural person or other actor is unknown. See also: pseudonym.
assurance level
A level of confidence that may be relied on by others. Different types of assurance levels are defined for different types of trust assurance mechanisms. Examples include authenticator assurance level, federation assurance level, and identity assurance level.
authorization
The process of verifying that a requested action or service is approved for a specific entity. Source: NIST-CSRC.
out-of-band introduction
A process by which two or more entities exchange VIDs in order to form a cryptographically verifiable connection (e.g., a ToIP connection), such as by scanning a QR code (in person or remotely) or clicking a deep link.
out-of-band introduction
A process by which two or more entities exchange VIDs in order to form a cryptographically verifiable connection (e.g., a ToIP connection), such as by scanning a QR code (in person or remotely) or clicking a deep link.
permission
Authorization to perform some action on a system.
policy
Statements, rules or assertions that specify the correct or expected behavior of an entity.
NIST-CSRC
NIST Computer Security Resource Center Glossary