diff --git a/v2/api/WIP.toip.trustregistry.api.yaml b/v2/api/WIP.toip.trustregistry.api.yaml index dc081e9..22d7434 100644 --- a/v2/api/WIP.toip.trustregistry.api.yaml +++ b/v2/api/WIP.toip.trustregistry.api.yaml @@ -5,7 +5,15 @@ servers: url: https://virtserver.swaggerhub.com/darrellodonnell/ToIP.TrustRegistry/0.1.0 info: description: | - TODO: update description + TODO: update description + # Trust Registry capabilities + * List Assurance levels - TODO: + * List namespaces supported - TODO: + # Registry of Registries (RoR) capabilities. + RoR capabilities include: + * signaling basic acknowledgement of other registries. + * list the acknowledged trust registries that the RoR recognizes and what + that may mean in the context of a particular governance framework. version: "0.2.0" title: Trust Over IP Trust Registry Protocol (RESTful API) v2 contact: @@ -88,7 +96,9 @@ paths: get: tags: - new-v2-query - summary: Query this Trust Registry about its recognition of another Trust Registry + summary: | + Query this Trust Registry about its recognition of another Trust Registry. + TODO: determine RoR (registry of registry) impacts here. parameters: - in: query name: trustregistryidentifier @@ -141,6 +151,35 @@ paths: $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' + /lookup/namespaces: + + get: + tags: + - new-v2-lookup + summary: Get a list of the namespaces that this trust registry supports. + parameters: + - in: query + name: egfURI + required: true + schema: + $ref: '#/components/schemas/Uri' + description: | + The URI-based identifier of a DID or X.509 Issuer. Allows reserved characters per RFC3986. + Do **NOT** escape the URI. + allowReserved: true # allow reserved characters per RFC3986 + responses: + '200': + description: search results matching criteria + content: + application/json: + schema: + $ref: '#/components/schemas/PLACEHOLDER' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' /lookup/rights: get: @@ -454,6 +493,27 @@ components: - "en-CA" - "fr-CA" # TODO: apply AssuranceLevel to Authorization. + Namespace: + type: object + description: | + Namespace object - formal name, EGF that governs namespace, VC/DIDAuth/etc. + required: + - namespaceDID + - namespace + properties: + namespaceDID: + type: string + format: URI + example: 'did:example:123' + namespace: + type: string + example: + - "ca.issuer.driverlicense" + - "mining.tsm" + egfURI: + type: string + + AssuranceLevel: type: object description: | @@ -491,6 +551,7 @@ components: description: type: string example: "Established on June 14, 1922, Professional Engineers Ontario (PEO) is the licensing and regulating body for professional engineering in the province." + peerType: type: string enum: diff --git a/v2/logical/highlevel.plantuml b/v2/logical/highlevel.plantuml index d5a9850..3f18879 100644 --- a/v2/logical/highlevel.plantuml +++ b/v2/logical/highlevel.plantuml @@ -23,7 +23,7 @@ class RegistryOfRegistries { } class Query { - EntityAuthorization(entity, right) + EntityAuthorization(entity, authorization) RecognizedRegistry(registryDID) GetResource(resourceDID) } @@ -37,6 +37,7 @@ class Lookup { ' PresentationRequests() ' Overlays() AssuranceLevels() + Namespaces() } class Metadata { @@ -45,6 +46,7 @@ class Metadata { RawAPIEndpoint: URL AuthorityClaim: string lastUpdated: datetime + namespaces: string[] Languages() @@ -55,7 +57,7 @@ EGF "1" -- "1" TrustRegistry TrustRegistry <|-- Query TrustRegistry <|-- Lookup -ww + package QueryDataObjects { object EntityAuthorizationResponse { entityid diff --git a/v2/requirements.md b/v2/requirements.md index d5e6bc0..daa0645 100644 --- a/v2/requirements.md +++ b/v2/requirements.md @@ -40,6 +40,7 @@ To comply with the intellectual property rights protections in[ the charter of t **Editors** +* Darrell O'Donnell, Continuum Loop **Contributors** @@ -67,8 +68,10 @@ All other terms in **bold** will be defined in one or more ToIP glossaries in th **Governing authorities** compliant with this specification: 1. MUST have exactly one **primary trust registry**. -2. MAY have zero or more **secondary trust registries**. (The **primary trust registry** plus all **secondary trust registries** are collectively the **authorized trust registries**.) -3. MUST publish an **EGF** that meets the **requirements** in: +2. MAY have one or more **secondary trust registries**. + +The **primary trust registry** plus all **secondary trust registries** are collectively referred to as the **authorized trust registries**. +3. MUST publish an **EGF** that meets the **requirements** of: - i. This specification. - ii. The [ToIP Governance Architecture Specification](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241). Note that this includes the requirement that the **EGF** and all **governed parties** (which includes **authorized issuers** and **authorized verifiers**) must be identified with a **DID**. 4. MUST publish, in the **DID document** associated with the **DID** identifying its **EGF**, a **service property **specifying the **service endpoint** for its **primary trust registry** that meets the **requirements** in the _[Trust Registry Service Property](#trust-registry-service-property)_ section. @@ -79,16 +82,17 @@ All other terms in **bold** will be defined in one or more ToIP glossaries in th - iii. Operational **requirements**. - iv. Legal contracts. 7. MUST specify in its **EGF** (or in any referenced **credential governance framework**) **requirements** for: - - i. An **authorized issuer**, including: - - a. The **EGF URI** that MUST be included as a **claim** in any authorized **credential**. - - b. The **credential type URI** that MUST be used for any authorized **credential**. - - ii. An **authorized verifier**, including: - a. The **presentation type URI** that an **authorized verifier** MUST use for any authorized **presentation request**. + - i. all `authorization` values that are used by the trust registry. + - ii. all Assurance Levels, specified with unique names, that are service by the trust registry. + - iii. all DID Methods that are supported by the ecosystem, and serviced by the trust registry. + - iv. all related resources that are to be serviced by the trust registry. + - v. any metadata required by implementors (e.g. claim name that is mandatory if pointing a credential back to an EGF.) [this is a weak example] + - vi. on which basis the trust registry claims to be authoritative + - vii. means by which others are able to verify the asserted authority 8. SHOULD specify in the **EGF** the following **requirements** for an **authorized trust registry** and any **registered party** (i.e., issuer, verifier, or peer trust registry): - - i. The set of **DID methods** authorized for use in the ecosystem. - - ii. The **requirements** to become authorized. - - iii. How to request registration. - - iv. The **requirements** for assignment of each **status value** for a **registry entry**. + - i. The **requirements** to become authorized. + - ii. How to request registration. + - iii. The **requirements** for assignment of each **authorization** for a **registry entry**. - v. Access control mechanisms. - vi. How to request access. @@ -102,6 +106,8 @@ The **DID document** for the **DID** that identifies an **EGF** compliant with t * The value of the `type` property MUST be `TrustRegistry`. * The value of the `serviceEndpoint` property MUST be exactly one HTTPS URI. +`TODO:` reconcile above with Profiles concept. + # Trust Registry Protocol @@ -111,10 +117,8 @@ The authoritative technical specifications for the API calls in the ToIP Trust R 1. MUST maintain the service implementing this protocol at the HTTPS URI specified in the _[Trust Registry Service Property](#trust-registry-service-property)_ section. 2. 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: - - i. **Authorized issuers**: EGF URI, **credential type URI**, issuer URI - - ii. **Authorized verifiers**: EGF URI, **presentation type URI**, verifier URI - - iii. **Trusted peer registries for authorized issuers:** EGF URI, **credential type URI**, EGF URI - - iv. **Trusted peer registries for authorized verifiers:** EGF URI, **presentation type URI**, EGF URI + - i. **Entity Authorization**: entityDID, authorization + - ii. **Recognized Registry:** entityDID 3. MUST return responses using the data model specified in the _[Data Model](#data-model)_ section. 4. MUST return exactly one of the following **status values** for a **registry entry** satisfying the query parameters: - i. `Not found` @@ -138,16 +142,19 @@ The authoritative technical specifications for the API calls in the ToIP Trust R # Data Model +`TODO:` build out data model pieces - do work on OAS/Swagger, then move here. # Appendix 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.` + | Req # | Description | Section | |---------|--------------|-----------| | | **General ToIP Architecture Requirements**| | | A.1 | MUST have exactly one **primary trust registry**. | [LINK] | |A.2 | MAY have zero or more **secondary trust registries**. (The **primary trust registry** plus all **secondary trust registries** are collectively the **authorized trust registries**.) | [LINK]| -|A.3|MUST publish an **EGF** that meets the **requirements** in: - 1. This specification. - 2. The [ToIP Governance Architecture Specification](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241). Note that this includes the requirement that the **EGF** and all **governed parties** (which includes **authorized issuers** and **authorized verifiers**) |[LINK]| +|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](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241). Note that this includes the requirement that the **EGF** and all **governed parties** (which includes **authorized issuers** and **authorized verifiers**) |[LINK]|