From a262760c5bde97e3dad1880bc7267c4e8d979f9c Mon Sep 17 00:00:00 2001 From: cl0ete Date: Tue, 22 Oct 2024 15:46:33 +0200 Subject: [PATCH 01/10] add mermaid to recommended --- .vscode/extensions.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.vscode/extensions.json b/.vscode/extensions.json index abb1a585b..bff52bba8 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,5 +1,6 @@ { "recommendations": [ + "bierner.markdown-mermaid", "editorconfig.editorconfig", "esbenp.prettier-vscode", "ms-python.black-formatter", From dcd04e9e2506f6adf38a94e6045c9f2077d4f920 Mon Sep 17 00:00:00 2001 From: cl0ete Date: Tue, 22 Oct 2024 15:47:21 +0200 Subject: [PATCH 02/10] add image_url to actor example --- docs/Trust Registry.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index bf5018614..ba7f47722 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -30,7 +30,8 @@ retrieved from requesting the endpoint. Their structures are as follows: ], "did": "did:sov:XfbLjZFxgoznN24LUVxaQH", "id": "test-actor-0.26703024264670694", - "didcomm_invitation": null + "didcomm_invitation": null, + "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png" }, ... } From 9cdb4c371550ef87ef37bf0936fd59aca64d2a31 Mon Sep 17 00:00:00 2001 From: cl0ete Date: Tue, 22 Oct 2024 15:49:07 +0200 Subject: [PATCH 03/10] add TR cred_def flow --- docs/Trust Registry.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index ba7f47722..fd4e69865 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -57,3 +57,31 @@ where `"z5Bug71M7Sj7cYpbVBDmN:2:test_schema:0.3"` represents the schema ID, name > **_NOTE_**: In a production environment, this should not be exposed to the internet or interacted with directly. > It's advisable to either avoid exposing this to the internet or set up a separate security layer for the trust > registry. This is because it's crucial to prevent unauthorized individuals from making changes to the trust registry. + +## Trust-registry Role in the application flows + +Below we indicate where and how the Trust-registry is consulted to verify that Issuers/Verifiers and schemas are on the +Trust-registry. + +### Create Credential Definition + +```mermaid +--- +title: Trust-registry called during credential definition creation +--- +flowchart LR + App(Create Credential Definition Request) -->|Consults| TR[Trust Registry] + subgraph Trust Registry Checks + TR -->|Validates| Check1{Issuer Authorization} + Check1 -->|If Unauthorized| Block[⨯ Block Operation] + Check1 -->|If Authorized| Check2{Schema exists on TR} + Check2 -->|Not on TR| Block + end + Check2 -->|If Registered| Continue[✓ Proceed with Creation] + + style TR fill:#a8d1ff,stroke:#1e88e5,color:black + style Block fill:#ffcdd2,stroke:#e53935,color:black + style Continue fill:#c8e6c9,stroke:#43a047,color:black +``` + +--- From e044bab06d0b1bc6bb9361c9fbc399cbbe51afd0 Mon Sep 17 00:00:00 2001 From: cl0ete Date: Tue, 22 Oct 2024 15:49:49 +0200 Subject: [PATCH 04/10] add TR credentials issuance flow --- docs/Trust Registry.md | 63 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index fd4e69865..c0ff53f7b 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -85,3 +85,66 @@ flowchart LR ``` --- + +### Credential issuance + +```mermaid +--- +title: Create Credential-Offer/Sending Credential +--- +flowchart LR + subgraph Request Types + App1(Create Offer Request
Connectionless) --> Consults[Consults] + App2(Send Credential Request
with Connection ID) --> Consults[Consults] + end + subgraph Trust Registry Checks + Consults --> TR + TR[Trust Registry] -- Validates --> Check1{Issuer
Authorization} + Check1 -->|If Unauthorized| Block[⨯ Block Operation] + Check1 -->|If Authorized| Check2{Schema
Registration} + Check2 -->|Not on TR| Block + end + Check2 -->|If Registered| Proceed[Continue] + + + subgraph Request Continue + Proceed -->|Connectionless| Continue1[✓ Create Offer] + Proceed -->|With Connection ID| Continue2[✓ Send Credential] + end + + linkStyle 0,8 stroke:#ff7043,color:#ff7043, stroke-width:2 + linkStyle 1,9 stroke:#7cb342,color:#7cb342,stroke-width:2 + + style TR fill:#a8d1ff,stroke:#1e88e5,color:black + style Block fill:#ffcdd2,stroke:#e53935,color:black + style Continue1 fill:#c8e6c9,stroke:#43a047,color:black + style Continue2 fill:#c8e6c9,stroke:#43a047,color:black + style Proceed fill:#c8e6c9,stroke:#43a047,color:black + +``` + +--- + +```mermaid +--- +title: Holder Request Credential +--- +flowchart LR + Start(Holder receives
Credential-Offer) --> Request[Request Credential] + Request -->|Consults| TR[Trust Registry] + subgraph Trust Registry Checks + TR -->|Validates| Check1{Issuer Authorization} + Check1 -->|If Unauthorized| Block[⨯ Block Operation] + Check1 -->|If Authorized| Check2{Schema exists on TR} + Check2 -->|Not on TR| Block + end + Check2 -->|If Registered| Continue[✓ Proceed with Credential Exchange] + + style TR fill:#a8d1ff,stroke:#1e88e5,color:black + style Block fill:#ffcdd2,stroke:#e53935,color:black + style Continue fill:#c8e6c9,stroke:#43a047,color:black +``` + +--- + +--- From 1872538370d56a40f6274886837d0fd27f963488 Mon Sep 17 00:00:00 2001 From: cl0ete Date: Tue, 22 Oct 2024 15:50:53 +0200 Subject: [PATCH 05/10] add Proof request TR flow --- docs/Trust Registry.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index c0ff53f7b..0cbd5b1f6 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -147,4 +147,46 @@ flowchart LR --- +### Proof Requests + +```mermaid +--- +title: Verifier sends Proof Request +--- +flowchart LR + Start(Send Proof request) -->|Consult| TR[Trust-Registry] + subgraph Trust Registry Checks + TR -->|Validates| Check1{Verifier Authorization} + Check1 -->|If Unauthorized| Block[⨯ Block Operation] + Check1 -->|If Authorized| Check2{Schema exists on TR} + Check2 -->|Not on TR| Block + end + Check2 -->|If Registered| Continue[✓ Proceed with
Sending Proof] + + style TR fill:#a8d1ff,stroke:#1e88e5,color:black + style Block fill:#ffcdd2,stroke:#e53935,color:black + style Continue fill:#c8e6c9,stroke:#43a047,color:black +``` + +--- + +```mermaid +--- +title: Holder Receives Proof Request +--- +flowchart LR + Start(Accept Proof Request) -->|Consult| TR[Trust-Registry] + subgraph Trust Registry Checks + TR -->|Validates| Check1{Verifier Authorization} + Check1 -->|If Unauthorized| Block[⨯ Block Operation] + Check1 -->|If Authorized| Check2{Schema exists on TR} + Check2 -->|Not on TR| Block + end + Check2 -->|If Registered| Continue[✓ Proceed with
Accepting Proof] + + style TR fill:#a8d1ff,stroke:#1e88e5,color:black + style Block fill:#ffcdd2,stroke:#e53935,color:black + style Continue fill:#c8e6c9,stroke:#43a047,color:black +``` + --- From 9366eb0ed263b79df68bce900e9688fa537e82cd Mon Sep 17 00:00:00 2001 From: cl0ete Date: Wed, 23 Oct 2024 08:26:49 +0200 Subject: [PATCH 06/10] some minor edits --- docs/Trust Registry.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index 0cbd5b1f6..0b318a724 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -58,9 +58,9 @@ where `"z5Bug71M7Sj7cYpbVBDmN:2:test_schema:0.3"` represents the schema ID, name > It's advisable to either avoid exposing this to the internet or set up a separate security layer for the trust > registry. This is because it's crucial to prevent unauthorized individuals from making changes to the trust registry. -## Trust-registry Role in the application flows +## Trust-registry Role in application flows -Below we indicate where and how the Trust-registry is consulted to verify that Issuers/Verifiers and schemas are on the +Below we indicate where and how the Trust-registry is consulted to verify that Issuers/Verifiers and Schemas are on the Trust-registry. ### Create Credential Definition @@ -94,8 +94,8 @@ title: Create Credential-Offer/Sending Credential --- flowchart LR subgraph Request Types - App1(Create Offer Request
Connectionless) --> Consults[Consults] - App2(Send Credential Request
with Connection ID) --> Consults[Consults] + App1(Create Offer
Connectionless) --> Consults[Consults] + App2(Send Credential
with Connection ID) --> Consults[Consults] end subgraph Trust Registry Checks Consults --> TR From e082795b1569bf83561fc4add34660478f093d8f Mon Sep 17 00:00:00 2001 From: cl0ete Date: Wed, 23 Oct 2024 09:19:01 +0200 Subject: [PATCH 07/10] :art: --- docs/Trust Registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index 0b318a724..c939f5e1e 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -151,7 +151,7 @@ flowchart LR ```mermaid --- -title: Verifier sends Proof Request +title: Verifier Sends Proof Request --- flowchart LR Start(Send Proof request) -->|Consult| TR[Trust-Registry] From f72aff50dcb12466de42b7353cc5869045d90515 Mon Sep 17 00:00:00 2001 From: cl0ete Date: Tue, 5 Nov 2024 08:33:38 +0200 Subject: [PATCH 08/10] refine Trust Registry documentation for application flows and interactions --- docs/Trust Registry.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index c939f5e1e..a49c05db3 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -58,16 +58,20 @@ where `"z5Bug71M7Sj7cYpbVBDmN:2:test_schema:0.3"` represents the schema ID, name > It's advisable to either avoid exposing this to the internet or set up a separate security layer for the trust > registry. This is because it's crucial to prevent unauthorized individuals from making changes to the trust registry. -## Trust-registry Role in application flows +## Trust Registry Interactions During Application Flows -Below we indicate where and how the Trust-registry is consulted to verify that Issuers/Verifiers and Schemas are on the -Trust-registry. +Below, we outline where and how the Trust Registry is consulted to verify that Issuers, Verifiers, and Schemas are +compliant. ### Create Credential Definition +When an issuer calls the create credential definition endpoint, the Trust Registry is consulted to confirm that the +tenant making the request is registered as an issuer and that the schema linked to the credential definition is also +listed on the Trust Registry. + ```mermaid --- -title: Trust-registry called during credential definition creation +title: Trust Registry called during credential definition creation --- flowchart LR App(Create Credential Definition Request) -->|Consults| TR[Trust Registry] @@ -86,7 +90,11 @@ flowchart LR --- -### Credential issuance +### Credential Issuance + +When an issuer sends a credential or attempts to create a credential offer, the Trust Registry is consulted to verify +that the requesting tenant is registered as an issuer and that the schema associated with the credential definition +(credential issued against `cred_def`) is also listed on the Trust Registry. ```mermaid --- @@ -125,6 +133,10 @@ flowchart LR --- +When a holder responds to a credential offer by requesting the credential offers to him. The Trust Registry is consulted +to verify that the issuer offering him the credential is registered as an issuer and that the schema associated with the +credential is also listed on the Trust Registry. + ```mermaid --- title: Holder Request Credential @@ -149,6 +161,9 @@ flowchart LR ### Proof Requests +When a verifier sends a proof request, the Trust Registry is consulted to confirm that the requesting tenant is registered +as a verifier and that the attributes requested in the proof are linked to a schema listed in the Trust Registry. + ```mermaid --- title: Verifier Sends Proof Request @@ -170,6 +185,10 @@ flowchart LR --- +When a prover (holder) responds to a proof request, the Trust Registry is consulted to confirm that the verifier sending +the request is registered and that the schema associated with the requested attributes is also listed in the +Trust Registry. + ```mermaid --- title: Holder Receives Proof Request From 610d0b3fcb6a12a807e09f8c75d211da945f1be3 Mon Sep 17 00:00:00 2001 From: ff137 Date: Wed, 13 Nov 2024 14:16:08 +0200 Subject: [PATCH 09/10] :art: Update docs and reduce charts to 1 for issuer and 1 for verifier --- docs/Trust Registry.md | 137 +++++++++-------------------------------- 1 file changed, 28 insertions(+), 109 deletions(-) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index a49c05db3..1e04bbebb 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -63,149 +63,68 @@ where `"z5Bug71M7Sj7cYpbVBDmN:2:test_schema:0.3"` represents the schema ID, name Below, we outline where and how the Trust Registry is consulted to verify that Issuers, Verifiers, and Schemas are compliant. -### Create Credential Definition +### Issuer Actions -When an issuer calls the create credential definition endpoint, the Trust Registry is consulted to confirm that the -tenant making the request is registered as an issuer and that the schema linked to the credential definition is also -listed on the Trust Registry. +When a user/tenant initiates any issuer-related action, the Trust Registry is used to verify the following: -```mermaid ---- -title: Trust Registry called during credential definition creation ---- -flowchart LR - App(Create Credential Definition Request) -->|Consults| TR[Trust Registry] - subgraph Trust Registry Checks - TR -->|Validates| Check1{Issuer Authorization} - Check1 -->|If Unauthorized| Block[⨯ Block Operation] - Check1 -->|If Authorized| Check2{Schema exists on TR} - Check2 -->|Not on TR| Block - end - Check2 -->|If Registered| Continue[✓ Proceed with Creation] - - style TR fill:#a8d1ff,stroke:#1e88e5,color:black - style Block fill:#ffcdd2,stroke:#e53935,color:black - style Continue fill:#c8e6c9,stroke:#43a047,color:black -``` - ---- +1. Issuer Verification: + - For **creating credential definitions**, **creating credential offers**, and **issuing credentials**: + Confirms that the tenant is registered with the role of an issuer. + - For **accepting credentials**: Confirms that the tenant is receiving a credential from a registered issuer. +2. Schema Validation: Ensures that the referenced schema is valid and registered within the Trust Registry. -### Credential Issuance - -When an issuer sends a credential or attempts to create a credential offer, the Trust Registry is consulted to verify -that the requesting tenant is registered as an issuer and that the schema associated with the credential definition -(credential issued against `cred_def`) is also listed on the Trust Registry. +If either step fails, the operation is blocked, and an appropriate error message is returned to the user. +The operation is logged and able to be reviewed by an administrator. ```mermaid --- -title: Create Credential-Offer/Sending Credential +title: Trust Registry called during issuer operations --- flowchart LR - subgraph Request Types - App1(Create Offer
Connectionless) --> Consults[Consults] - App2(Send Credential
with Connection ID) --> Consults[Consults] - end + App(Issuer Action:
Credential Operations) -->|Consults| TR[Trust Registry] subgraph Trust Registry Checks - Consults --> TR - TR[Trust Registry] -- Validates --> Check1{Issuer
Authorization} + TR -->|Validates| Check1{Issuer Verification} Check1 -->|If Unauthorized| Block[⨯ Block Operation] - Check1 -->|If Authorized| Check2{Schema
Registration} + Check1 -->|If Authorized| Check2{Schema Validation} Check2 -->|Not on TR| Block end - Check2 -->|If Registered| Proceed[Continue] - - - subgraph Request Continue - Proceed -->|Connectionless| Continue1[✓ Create Offer] - Proceed -->|With Connection ID| Continue2[✓ Send Credential] - end + Check2 -->|If Registered| Continue[✓ Proceed with Operation] - linkStyle 0,8 stroke:#ff7043,color:#ff7043, stroke-width:2 - linkStyle 1,9 stroke:#7cb342,color:#7cb342,stroke-width:2 - style TR fill:#a8d1ff,stroke:#1e88e5,color:black style Block fill:#ffcdd2,stroke:#e53935,color:black - style Continue1 fill:#c8e6c9,stroke:#43a047,color:black - style Continue2 fill:#c8e6c9,stroke:#43a047,color:black - style Proceed fill:#c8e6c9,stroke:#43a047,color:black - + style Continue fill:#c8e6c9,stroke:#43a047,color:black ``` --- -When a holder responds to a credential offer by requesting the credential offers to him. The Trust Registry is consulted -to verify that the issuer offering him the credential is registered as an issuer and that the schema associated with the -credential is also listed on the Trust Registry. - -```mermaid ---- -title: Holder Request Credential ---- -flowchart LR - Start(Holder receives
Credential-Offer) --> Request[Request Credential] - Request -->|Consults| TR[Trust Registry] - subgraph Trust Registry Checks - TR -->|Validates| Check1{Issuer Authorization} - Check1 -->|If Unauthorized| Block[⨯ Block Operation] - Check1 -->|If Authorized| Check2{Schema exists on TR} - Check2 -->|Not on TR| Block - end - Check2 -->|If Registered| Continue[✓ Proceed with Credential Exchange] - - style TR fill:#a8d1ff,stroke:#1e88e5,color:black - style Block fill:#ffcdd2,stroke:#e53935,color:black - style Continue fill:#c8e6c9,stroke:#43a047,color:black -``` +### Verifier Actions ---- +When a tenant initiates any verifier-related action (sending proof requests or receiving proof presentations), +the Trust Registry is used to verify the following: -### Proof Requests +1. Verifier Verification: + - For **sending proof requests**: Confirms that the tenant sending the request is registered as a verifier. + - For **receiving proof presentations**: Validates that the proof is being presented to a registered verifier. +2. Schema Validation: Ensures that the attributes being requested are associated with schemas registered + within the Trust Registry. -When a verifier sends a proof request, the Trust Registry is consulted to confirm that the requesting tenant is registered -as a verifier and that the attributes requested in the proof are linked to a schema listed in the Trust Registry. +If either step fails, the operation is blocked as a bad request, with an appropriate error message returned to the user. ```mermaid --- -title: Verifier Sends Proof Request +title: Trust Registry called during proof requests --- flowchart LR - Start(Send Proof request) -->|Consult| TR[Trust-Registry] + Start(Verifier Action:
Proof Request Operations) -->|Consult| TR[Trust Registry] subgraph Trust Registry Checks - TR -->|Validates| Check1{Verifier Authorization} + TR -->|Validates| Check1{Verifier Verification} Check1 -->|If Unauthorized| Block[⨯ Block Operation] Check1 -->|If Authorized| Check2{Schema exists on TR} Check2 -->|Not on TR| Block end - Check2 -->|If Registered| Continue[✓ Proceed with
Sending Proof] - - style TR fill:#a8d1ff,stroke:#1e88e5,color:black - style Block fill:#ffcdd2,stroke:#e53935,color:black - style Continue fill:#c8e6c9,stroke:#43a047,color:black -``` + Check2 -->|If Registered| Continue[✓ Proceed with Operation] ---- - -When a prover (holder) responds to a proof request, the Trust Registry is consulted to confirm that the verifier sending -the request is registered and that the schema associated with the requested attributes is also listed in the -Trust Registry. - -```mermaid ---- -title: Holder Receives Proof Request ---- -flowchart LR - Start(Accept Proof Request) -->|Consult| TR[Trust-Registry] - subgraph Trust Registry Checks - TR -->|Validates| Check1{Verifier Authorization} - Check1 -->|If Unauthorized| Block[⨯ Block Operation] - Check1 -->|If Authorized| Check2{Schema exists on TR} - Check2 -->|Not on TR| Block - end - Check2 -->|If Registered| Continue[✓ Proceed with
Accepting Proof] - style TR fill:#a8d1ff,stroke:#1e88e5,color:black style Block fill:#ffcdd2,stroke:#e53935,color:black style Continue fill:#c8e6c9,stroke:#43a047,color:black ``` - ---- From 52e6eac07662060103fd7046fc661b5b7dcd15fc Mon Sep 17 00:00:00 2001 From: ff137 Date: Wed, 13 Nov 2024 14:25:50 +0200 Subject: [PATCH 10/10] :art: --- docs/Trust Registry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Trust Registry.md b/docs/Trust Registry.md index 1e04bbebb..720fb777a 100644 --- a/docs/Trust Registry.md +++ b/docs/Trust Registry.md @@ -58,7 +58,7 @@ where `"z5Bug71M7Sj7cYpbVBDmN:2:test_schema:0.3"` represents the schema ID, name > It's advisable to either avoid exposing this to the internet or set up a separate security layer for the trust > registry. This is because it's crucial to prevent unauthorized individuals from making changes to the trust registry. -## Trust Registry Interactions During Application Flows +## Trust Registry Interactions Below, we outline where and how the Trust Registry is consulted to verify that Issuers, Verifiers, and Schemas are compliant. @@ -104,7 +104,7 @@ the Trust Registry is used to verify the following: 1. Verifier Verification: - For **sending proof requests**: Confirms that the tenant sending the request is registered as a verifier. - - For **receiving proof presentations**: Validates that the proof is being presented to a registered verifier. + - For **accepting proof requests**: Validates that the proof is being presented to a registered verifier. 2. Schema Validation: Ensures that the attributes being requested are associated with schemas registered within the Trust Registry.