Commit 51ee69d9 authored by Rieks Joosten's avatar Rieks Joosten

Work in progress (suitable to be merged)

parent bc70a51b
Pipeline #15715 passed with stage
in 1 minute and 59 seconds
# eSSIF-Lab Framework
This repo contains the source documents of the [eSSIF-Lab framework](https://essif-lab.pages.grnet.gr/framework/), such as its vision, architecture and other relevant topics.
This repo contains files that are used to generate the the [eSSIF-Lab framework](https://essif-lab.pages.grnet.gr/framework/) website, which includes the eSSIF-Lab vision, functional architecture, terminology and other relevant topics.
## Writing docs
This website is generated using [Docusaurus 2](https://v2.docusaurus.io/) (and a custom plugin developed by [GRNET](https://grnet.gr/en/) for handling terminology).
This website is built using [Docusaurus 2](https://v2.docusaurus.io/).
## Writing Docusaurus Documents
Documentation content must appear in `.md` files inside the `docs` folder.
Docusaurs requires documentation content to appear in `.md` files inside the `docs` folder.
Each file defines the following attributes at its very beginning:
- `id`, by which the file is referred to across the project
- `title`, appearing at the top of the file's display
- `sidebar_label`, the file's name appearing in the sidebar
The `sidebars.js` file contains the basic mechanism for distributing content
among sections and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/introduction)). Subsections within the `.md` file
(that is, tagged with `##`) will appear at the right part of the page
(see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)).
Documentation on these and other header fields can be found [here](https://v2.docusaurus.io/docs/markdown-features#markdown-headers).
Images must be put inside the directory `static/images` and developers must refer to them using _relative_ urls.
The Terminology Engine plugin of GRNET uses additional header fields. These are (or will be) defined [here](./docs/terminology-contributions).
The `sidebars.js` file contains the basic mechanism for [distributing content among sections](https://v2.docusaurus.io/docs/docs-introduction#sidebar) and is self-explanatory (compare with the sidebar appearing [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/introduction)). Subsections within the `.md` file (that is, tagged with `##`) will appear at the right part of the page (see for example [here](https://essif-lab.pages.grnet.gr/essif-lab/docs/infrastructure)).
## Inserting Images in docs
<!-- **DEPRECATED** Images must be put inside the directory `static/images` and developers must refer to them using _relative_ urls.
Example: ![eSSIF-Lab logo](../images/eSSIF-Lab%20logo.png)
Docusaurus knows that the `../images` directory is inside the `static` directory, and thus process correctly.
The deployment pipe will convert `../images/` in such links to their _*absolute*_ urls.
Of course, if you want to link to images on the web, you can still use absolute urls.
Of course, if you want to link to images on the web, you can still use absolute urls. -->
If you want to add an image, say `example.png`, here is what you do:
- first, add the image to the `/static/images` directory (or `/static/images/subdir-path/`)
- then, in your document, add a line behind the docusaurus header that says: `import useBaseUrl from '@docusaurus/useBaseUrl';`
- next, in your document, at the place where you want the image to be presented, insert the following snippet:
```html
<img
alt="text-that-shows-if-the-image-cannot-be-found"
src={useBaseUrl('images/example.png')}
/>
```
(or `src={useBaseUrl('images/subdir-path/example.png')}` if you added the image file there).
### Installation
......
......@@ -14,7 +14,11 @@ The purpose of the functional architecture and its views is to
## 1. Basic Terminology
In order to serve such purposes, we have found out that it is necessary that to make a strict and consequent distinction between people and Organizations that are capable of making decisions and bearing responsibility/accountability (we will use the term ‘%%Party|party%%’ for that) and people and ‘things’ that are capable of acting/doing things (we will use the term ‘%%Actor|actor%%’ for that). This means that an Organization is always a Party, whereas we consider a person to be a Party at one time and an Actor at another time, and computers/robots (and SSI components) are always an Actor.
In order to serve such purposes, we have found out that it is necessary that to make a strict and consequent distinction between people and Organizations that are capable of making decisions and bearing responsibility/accountability (we will use the term ‘%%Party|party%%’ for that) and people and ‘things’ that are capable of acting/doing things (we will use the term ‘%%Actor|actor%%’ for that). All %%Organizations|organization%% are %%Parties|party%%, whereas we consider a person (human being) to be both a %%Party|party%% (in cases where reasoning, decision making and bearing responsibility are in order), and an %%actor|actor%% (in cases where the person is actually doing things). More details backgrounds are given in the %%mental model|mental-model%% '%%Parties, Actors and Actions|pattern-party-actor-action%%' and the documentation of the concepts used therin.
:::note Editor's note
TNO to edit remainder of this section (make it shorter), because users can click on the various terms if they want to know more.
:::
This distinction is necessary because Actors do things that Parties are accountable for. In order to know which Party is accountable for what actions, we need the ability to link Parties and Actors. When an Actor acts and a (single) specific Party is accountable for that, we say that the Actor is an ‘%%Agent|agent%%’ for or of that Party (at that particular point in time). We say that this Actor acts ‘**on behalf of**’ that Party. Note that both humans and (running) applications may serve as Agents (human Agent or digital/electronic Agent respectively). A digital Agent that has one or more of the SSI functionalities we describe further down will be called an '%%SSI-Agent|ssi-agent%%', and we say that the Party on whose behalf it operates is the ‘%%Owner|owner%%’ of that Agent. Also, we use the term '**(digital/electronic or human) Colleague (of an Agent)**' to refer to any other (electronic or human) Agent that acts on behalf of the same Party as this Agent.
......@@ -26,7 +30,7 @@ Also, to serve the aforementioned purposes, we cannot fix the architecture (and
## 2. Functional Architecture Overview
Figure 1 shows the initial *functional* eSSIF-Lab architecture, and its scope, context and *functional* components each of which is a (*functional*) Agent for the same Party (meaning that they are all part of the same Organization as defined above, and they are all (digital) ‘Colleagues’ of one another).
Figure 1 shows the initial *functional* eSSIF-Lab architecture, and its scope, context and *functional* components each of which is a (*functional*) %%agent|agent%% for the same %%party|party%% (meaning that they are all part of the same %%organization|organization%% as defined above, and they are all %%(digital) ‘Colleagues’|digital-colleague%% of one another).
Please be aware that *functional* capabilities, components, Agents, etc. do not necessarily coincide with *technical* capabilities, components, Agents, etc. The technical components can be deployed (downloaded, installed, run), whereas a functional component is a provider of a specified set of capabilities/functionalities an implementation of which can be made part of a technical component. So it is conceivable that a technical component contains an implementation of wallet, holder and verifier functional components as well as other functionalities that are not described here, e.g. related to UX, setting preferences, and more. In this functional architecture, the default type of components, Agents etc. are *functional*.
......
......@@ -4,24 +4,23 @@ title: eSSIF-Lab Vision and Purpose
sidebar_label: Vision and Purpose
---
import useBaseUrl from '@docusaurus/useBaseUrl';
The eSSIF-Lab vision is that Self-sovereign Identity (SSI) will *empower European and other citizens* by providing new means to manage privacy by eliminating logins and making electronic transactions fast and safe both in the Internet and in physical life. SSI will *empower European organisations and governments* by providing new means to speed up, secure and automate transactions with citizens, customers, suppliers and partners, resulting in tens of billions of euros savings annually on administrative costs in Europe. SSI will be *a new business ecosystem paradigm* with thousands of new jobs, many new job categories and new business opportunities for existing and new European companies. And last, but certainly not least, SSI fosters *inclusiveness* and supports organizations and citizens to exercise their rights and fulfil their duties under the GDPR.
The current situation is that SSI solutions that are being created and brought to the market either target specific applications for which they provide a vertical solution (‘stovepipes’), many need some kind of centralized governance/control, others have privacy issues, and none that we know of are interoperable with other such solutions.
The situation we would like to see is one in which we have SSI-enabled, interoperable and scalable technologies, that form an infrastructure that every application in any vertical can use in a very easy manner, for the exchange of verified (personal and non-personal) data. In that situation people, businesses and governments think more about the information they need and/or provide as they conduct business transactions. They no longer need to be concerned about the SSI technologies that have empowered them to make this happen.
The situation we would like to see is one in which we have SSI-enabled, interoperable, scalable and business/information agnostic technologies, that form an infrastructure that every application for every party can use to serve its own objectives. This infrastructure, that enables the electronic exchange of verified (personal and non-personal) data, must be so easy to access and use for such parties that they will no longer need to be concerned about actual (SSI) technologies that have empowered them to make this happen. Rather, they will only need to think about, and decide which kinds of information they want to obtain for conducting specific business transactions and which parties they trust for providing such information. Also, they will need to think about, and decide which kinds of information they themselves are willing to provide to others in this new SSI world.
:::tip **The purpose of the eSSIF-Lab...**
... is to specify, develop and validate technological and non-technological means that support people, businesses and governments to think about, design and operate their (information) processes and (electronically) conduct business transactions with one another.
:::
The context of the eSSIF-Lab vision can be found in articles 8-10 of the [*European Convention on Human Rights (ECHR)*](https://www.echr.coe.int/Pages/home.aspx?p=basictexts/convention), that state the rights of individuals regarding their privacy, and their freedoms to collect, process, store, and express information in a self-sovereign fashion, i.e. in a way that they can decide for themselves. This is without prejudice to Member States’ laws that exist to protect their national security, public safety, the economic well-being of the country, health or morals or the rights and freedoms of others, or to prevent disorder or crime. The eSSIF-Lab vision extends these rights and freedoms - within the limits of the law - to public and private organizations. Thus, we say that individuals as well as public and private organizations (that we collectively refer to as ‘parties’) are self-sovereign<sup>[1]</sup>.
In the context of these rights and freedoms, we seek to support electronic business transactions, i.e. the electronic exchange of goods, services, funds, or data between parties, which we call ‘participants’ to the transaction<sup>[2]</sup>.
The context of the eSSIF-Lab vision can be found in articles 8-10 of the [*European Convention on Human Rights (ECHR)*](https://www.echr.coe.int/Pages/home.aspx?p=basictexts/convention), that state the rights of individuals regarding their privacy, and their freedoms to collect, process, store, and express information in a self-sovereign fashion, i.e. in a way that they can decide for themselves. This is without prejudice to Member States’ laws that exist to protect their national security, public safety, the economic well-being of the country, health or morals or the rights and freedoms of others, or to prevent disorder or crime. The eSSIF-Lab vision extends these rights and freedoms - within the limits of the law - to public and private organizations. Thus, we say that individuals as well as public and private organizations (that we collectively refer to as ‘parties’) are self-sovereign[^1].
An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic agent, i.e. equipment (e.g. an app on a mobile phone, a webserver, a browser, …) that acts on behalf of its owner in the transaction.
An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic agent, i.e. equipment (e.g. an app on a mobile phone, a web server, a browser, …) that acts on behalf of its owner in the transaction.
In the context of these rights and freedoms, we seek to support %%electronic business transactions|business-transaction%%, i.e. the electronic exchange of goods, services, funds, or data between parties, which we call ‘participants’ to the transaction[^2].
An electronic business transaction is a business transaction that requires each participant to have (at least one) electronic %%(digital) agent|digital-agent%%, i.e. equipment (e.g. an app on a mobile phone, a webserver, a browser, …) that acts on behalf of its owner in the transaction.
## High-Level Example of a Business Transaction
......@@ -33,18 +32,23 @@ Perhaps the most important contribution that the eSSIF-Lab project aims to make,
The figure below is a high-level visualization of the filling in and validation parts:
![eSSIF-Lab - vision context](https://essif-lab.pages.grnet.gr/framework//images/vision-context.png) *Figure 1. High-level visualization of the filling in and validation of a form.*
<img
alt="High-level visualization of the filling in and validation of a form."
src={useBaseUrl('images/vision-context.png')}
/>
*Figure 1. High-level visualization of the filling in and validation of a form.*
The transaction that is envisaged here is the issuing of a parking permit. Participants are a person (requestor) that requests such a permit, and an organization (provider) that can issue such a permit. The requestor has one electronic agent, *the Requestor Agent (RA)*, i.e. an SSI-aware app on their mobile phone that can access a secure storage that contains ‘credentials’, i.e. data that is digitally signed by some third party, thus attesting to the truth of that data. The provider has two agents: one is an SSI-aware component *Provider Agent (PA_* that works with the web-server that presents the form, and the other is a person *P* whose task is to validate any data (on behalf of the provider) that is not validated electronically. The form itself contains a means, e.g. a QR-code or a deep-link, that allows *RA* and *PA* to set up a secure communications channel (e.g. SSL, [DIDComm](https://openssi.github.io/peer-did-method-spec/)) and agree on the specific form that needs to be filled in.
After the *RA* and *PA* have established a communications channel and agree on the form to be filled in, *PA* informs *RA* about the information it needs to fill in the form, and the requirements that this information should satisfy<sup>[3]</sup>. *RA* then checks its data store to see whether or not such data is available, sends such data to *PA*, which subsequently validates it and uses it to fill in (appropriate parts of) the form. Finally, *P* validates the remaining data, which either results in a ‘clean’ form, i.e. a form that contains valid data that can subsequently be used to decide whether or not to provide the parking permit, or a message to the requester informing him about missing and/or invalid data.
After the *RA* and *PA* have established a communications channel and agree on the form to be filled in, *PA* informs *RA* about the information it needs to fill in the form, and the requirements that this information should satisfy[^3]. *RA* then checks its data store to see whether or not such data is available, sends such data to *PA*, which subsequently validates it and uses it to fill in (appropriate parts of) the form. Finally, *P* validates the remaining data, which either results in a ‘clean’ form, i.e. a form that contains valid data that can subsequently be used to decide whether or not to provide the parking permit, or a message to the requester informing him about missing and/or invalid data.
When the transaction has been completed, both participants can issue a credential that attests to the results of the transaction. For example, the provider could issue a credential stating that the requestor has obtained a parking permit for a car with a specific plate number (and other attributes). The requestor can store this credential and from that moment on use it in new electronic transactions.
--------
[1] We realize that by doing this we have a different definition of what self-sovereignty entails than many others. We are open to suggestions for a better phrase.
[^1]: We realize that by doing this we have a different definition of what self-sovereignty entails than many others. We are open to suggestions for a better phrase.
[2] A good mental model for describing and designing transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations).
[^2]: A good mental model for describing and designing transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations).
[3] Since transactions are symmetric, the requestor could also have a form that the provider needs to fill in so as to provide the requestor with the data it needs to commit to that transaction. We have left that out of this description for the sake of simplicity.
[^3]: Since transactions are symmetric, the requestor could also have a form that the provider needs to fill in so as to provide the requestor with the data it needs to commit to that transaction. We have left that out of this description for the sake of simplicity.
......@@ -4,7 +4,7 @@ title: "eSSIF-Lab Glossary"
sidebar_label: Glossary
---
:::note Editor's note
:::info Editor's note
TNO to write the introduction paragraph
Remainder of file to be generated (GRNET plugin/extension)
:::
......@@ -4,7 +4,7 @@ title: "eSSIF-Lab List of Patterns"
sidebar_label: Mental Models
---
:::note Editor's note
:::info Editor's note
TNO to write the introduction paragraph
Remainder of file to be generated (GRNET plugin/extension)
:::
---
id: business-transaction
title: "Business Transaction"
scopeid: essifLab
type: concept
typeid: business-transaction
stage: draft
hoverText: "Business Transaction: the electronic exchange of goods, services, funds, or data between parties (called‘participants’ to the transaction)"
---
:::info Editor's note
TNO to provide the content of this file.
:::
### Notes
1. A good mental model for describing and designing business transactions and their participants is provided by [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations).
\ No newline at end of file
---
id: colleague
title: "Colleague"
scopeid: essifLab
type: concept
typeid: colleague
stage: draft
hoverText: "Colleague (of an Agent): An actor that is an Agent for the same Principal."
---
:::info Editor's note
TNO to provide the content of this file.
:::
......@@ -7,3 +7,7 @@ typeid: corpus
stage: draft
hoverText: "Corpus (of Terminology): the documentation that describes the knowledge around a set of terms and concepts."
---
:::info Editor's note
TNO to provide the content of this file.
:::
---
id: credential
title: "Credential"
scopeid: essifLab
type: concept
typeid: credential
stage: draft
hoverText: "Credential: data, representing a set of statements made by one party (the author of the credential)."
---
:::info Editor's note
TNO to provide the content of this file.
:::
### Related Concepts
- %%verifiable credential|verifiable-credential%%
- %%verified data|verified-data%%
- %%validated data|validated-data%%
---
id: digital-colleague
title: "Digital Colleague"
scopeid: essifLab
type: term
typeid: digital-colleague
conceptref: ":Colleague"
stage: draft
hoverText: "Digital Colleague (of an Agent): a digital actor that is an agent of the same principal."
---
### Purpose
<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
The ability to distinguish between (non)digital colleagues allows us to reason and communicate about the set of %%digital actors|digital-actor%% that are %%agents|agent%% for a single **principal|principal%%.
See also: %%colleague|colleague%%.
......@@ -2,27 +2,18 @@
id: digital-policy
title: "Digital Policy"
scopeid: essifLab
type: term
type: concept
typeid: digital-policy
conceptref: ":Policy"
stage: draft
hoverText: "Digital Policy: a (set of) machine readable rules, working instructions or other guidance for the execution of one or more kinds of actions, that digital agents have access to and must use when executing such actions."
hoverText: "Digital Policy: a machine-readable document that contains rules, working instructions or other guidance for digital agents so as to enable them to execute actions on behalf of the author of that policy."
---
### Short Description
A **digital policy** is a (set of) machine readable rules, working instructions or other guidance for the execution of one or more kinds of %%actions|action%%. A %%digital agent|digital-agent%% must have access to the digital policy that its %%principal|principal%% has established for the kind of action that the agent is executing on the principal's behalf.
It should be part of the principal's governance processes to establish, maintain and evaluate digital policies for every kind of action that its agents may execute.
The principal must ensure that its %%digital actors|digital-actor%% can access the appropriate policies when needed.
A **digital policy** is an artifact that is derived from, and represents, a %%policy|policy%% for the purpose of being useable in the digital realm.
### Purpose
The purpose of **digital policies** is to enable %%parties|party%% to provide its %%digial agents|digital-agent%% with the rules and other guidance that they need to automaticallly execute %%actions|action%% that comply with such rules.
### Criterion
A **digital policy** is
- a (set of) machine readable rules, working instructions or other guidance for the execution of one or more kinds of %%actions|action%%;
- is authored by a single %%Party|party%% (the author or %%owner|owner%% of the digital policy);
- is accessable to, and must be complied with by a %%digital agent|digital-agent%% of that policy's author when it executes an action of the kind to which the digital policy applies.
<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
The ability to distinguish between (non)digital policies allows us to exclusively talk about machine-readable policies, i.e. policies that are to be used by harsoftware/hardware %%actors|actor%%.
See also: %%Policy|policy%%.
\ No newline at end of file
......@@ -9,13 +9,13 @@ hoverText: "Holder: a functional component that is capable of "
---
## Short Description
A **Holder** is an (architectural) function that handles Presentation Requests that it receives from %%verifier|verifier%% components (both of its %%owner|owner%%, and of other %%parties|party%%). Typically, this means looking for the requested data in the Owner’s %%wallet|wallet%%, and using it to construct a Presentation (=response). However, if the Wallet doesn’t have it, the Holder may negotiate a transaction with a component of the designated %%issuer|issuer%% for the purpose of obtaining the needed credential, which - when obtained - it can subsequently store in the wallet and use in the Presentation.
A **Holder** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that handles %%Presentation Requests|presentation-request%% that it receives from %%verifier|verifier%% components (of other %%parties|party%%, but also of its own %%owner|owner%%). Typically, this means looking for the requested data in the Owner’s %%wallet|wallet%%, and using it to construct a Presentation (=response). However, if the Wallet doesn’t have it, the Holder may negotiate a transaction with a component of the designated %%issuer|issuer%% for the purpose of obtaining the needed credential, which - when obtained - it can subsequently store in the wallet and use in the Presentation.
## Purpose
The purpose of the Holder component is to handle Presentation Requests that it receives from %%verifier|verifier%% components (both of its own %%owner|owner%%, and of other %%parties|party%%), and responding to such requests.
## Criteria
A **Holder** is a component in the [eSSIF-Lab functional architecture](..\functional-architecture\) whose function is to handle Presentation Requests that it receives from %%verifier|verifier%% components (both of its %%owner|owner%%, and of other %%Parties|party%%).
A **Holder** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whose function is to handle Presentation Requests that it receives from %%verifier|verifier%% components (both of its %%owner|owner%%, and of other %%Parties|party%%).
## Functionality
......
......@@ -9,14 +9,14 @@ hoverText: "Issuer: a functional component that is capable of "
---
## Short Description
The **issuer** is an (architectural) function that structures sets of (related) statements/claims (e.g. as produced by the %%TRD|trd%%) in a packate, adds metadata which includes e.g. a timestamp at which this was done, ensures that it is digitally signed on behalf of its %%owner|owner%%, signature by which third Parties can prove its provenance and integrity. Another function of the issuer is to handle revocation (and (un)suspension) of credentials that it has issued. For such tasks, it relies on functions that are made available by the SSI Protocols and Crypto Layer.
An **issuer** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that structures sets of (related) statements/claims (e.g. as produced by the %%TRD|trd%%) in a packate, adds metadata which includes e.g. a timestamp at which this was done, ensures that it is digitally signed on behalf of its %%owner|owner%%, signature by which third Parties can prove its provenance and integrity. Another function of the issuer is to handle revocation (and (un)suspension) of credentials that it has issued. For such tasks, it relies on functions that are made available by the SSI Protocols and Crypto Layer.
## Purpose
The purpose of the Issuer function is.
## Criteria
A **Issuer** is a component in the [eSSIF-Lab functional architecture](..\functional-architecture\) whose function is to ... (tbd).
A **Issuer** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whose function is to ... (tbd).
## Functionality
......
......@@ -9,4 +9,8 @@ stage: draft
hoverText: "Mental Model: a casual and formal description (pattern) of a set of concepts, relations between them, and constraints, that provide a specific 'viewpoint', or 'way of thinking' about a certain topic."
---
see: %%pattern|pattern%%.
\ No newline at end of file
:::info Editor's note
TNO to provide the content of this file.
:::
See also: %%pattern|pattern%%.
\ No newline at end of file
......@@ -10,6 +10,7 @@ hoverText: "The Mandates, Delegation and Hiring pattern (which remains to be doc
import useBaseUrl from '@docusaurus/useBaseUrl';
:::info Editors Note
TNO is expected to produce the first draft of this document
:::info Editor's note
TNO to provide the content of this file.
:::
......@@ -10,24 +10,6 @@ hoverText: "The eSSIF-Lab Terminology Pattern describes the relations between te
import useBaseUrl from '@docusaurus/useBaseUrl';
### Purpose
<!-- Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it. -->
### Introduction
<!-- Gently introduce the pattern, by referring to real-world situations and using colloquial terms, so that when someone has read the text, (s)he knows what it is about, and is ready to delve into the specifics of the pattern. -->
### Notations
<!-- This (optional) section specifies the notations that are used, or refers to such a specification. -->
## <!-- any number of other sections, as is fit for describing the pattern -->
<!-- text as appropriate for such a section -->
<!--
---
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
\ No newline at end of file
:::info Editor's note
TNO to provide the content of this file.
:::
---
id: policy
title: "Policy"
scopeid: essifLab
type: concept
typeid: policy
stage: draft
hoverText: "Policy: a (set of) rules, working instructions or other guidance for the execution of one or more kinds of actions, that agents (a) have access to, (b) can interpret as intended by their principal (i.e. policy owner) and (c) must use when executing such actions."
---
### Short Description
A **policy** is a (set of) rules, working instructions and/or other guidance for the execution of one or more kinds of %%actions|action%%. that agents (a) have access to, (b) can interpret as intended by their principal (i.e. policy owner) and (c) must use when executing such actions.
An %%agent|agent%% must have access to the policy that its %%principal|principal%% has established for the kind of action(s) that the agent is executing for its principal. This requires that the policy be readable by the agent, and that the agent is capable of interpreting it as intended by its principal.
It should be part of the %%principal's|principal%% governance processes
- to establish, maintain and evaluate policies for every kind of action that its agents may execute,
- to derive artifacts from such policies that are useable by the various %%agents|agent%% (digital, human, or otherwise) that have a right or duty to execute actions for the %%principal|principal%% to which such policies apply. So, machine-readable policies should be derived for %%digital-agents|digital-agent%%, and human-readable policies (in different languages if that is appropriate) for non-digital agents.
- to publish such artifacts such that at least every of its %%agents|agent%% that may need to access them, can find and access them as needed.
- to inform its %%agents|agent%% whenever updates have been made that they need to be aware of (specifically if agents are allowed to keep local copies of such artifacts).
### Purpose
The purpose of **policies** is to enable %%parties|party%% to provide its %%agents|agent%% with the rules and other guidance that they need to execute %%actions|action%% that comply with such rules.
### Criterion
A **policy** is
- a (set of) rules, working instructions and/or other guidance for the execution of one or more kinds of %%actions|action%%;
- is authored by a single %%Party|party%% (the author or %%owner|owner%% of the policy);
- may have multiple representations of the rules, working instructions and/or other guidance, which are derived from the policy itself, in such a way that that any %%actor|actor%% that has a right or duty to execute an %%action|action%% on behalf of the policy's author can do so according to its intentions;
- is accessable to, and must be complied with by an %%agent|agent%% of that policy's author when it executes an action of the kind to which the policy applies.
---
id: presentation-request
title: "Presentation Request"
scopeid: essifLab
type: concept
typeid: presentation-request
stage: draft
hoverText: "Presentation Request: a (signed) digital message that a verifier component sends to a holder component asking for data from one or more verifiable credentials."
---
:::info Editor's note
TNO to provide the content of this file.
:::
......@@ -8,16 +8,10 @@ stage: draft
hoverText: "Risk: the deviation of the expected realization (e.g. results) of an objective of a party."
---
:::info Editors Note
TNO is expected to produce the first draft of this document
:::info Editor's note
TNO to provide the content of this file.
:::
### Short Description
### Purpose
### Criterion
### References
[1]: NRM, [ISO 27000:2016](https://www.iso.org/obp/ui#iso:std:iso-iec:27000:ed-4:v1:en)
\ No newline at end of file
......@@ -6,13 +6,14 @@ type: term
typeid: ssi-agent
conceptref: essifLab:Agent
stage: draft
hoverText: "SSI-Agent: an agent that provides SSI services."
hoverText: "SSI-Agent: a digital agent that provides one or more of the SSI functionalities (issuer, holder, verifier, wallet) to its principal."
---
### Short Description
An **SSI-agent** is a %%digital agent|digital-agent%% that provides one or more of the SSI functionalities (i.e. %%issuer|issuer%%, %%holder|holder%%, %%verifier|verifier%%, %%wallet|wallet%%) to its %%principal|principal%%.
### Purpose
<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
The ability to distinguish between (non)SSI agents allows us to exclusively talk about agents that provide some or all of the SSI functionalities (i.e. %%issuer|issuer%%, %%holder|holder%%, %%verifier|verifier%%, %%wallet|wallet%%).
### Notes
<!--Usually, the meaning of a term will not be _exactly_ the same as that of the concept to which it refers. Often, there are slight differences in meaning, or the term may emphasize specific characteristics of the concept, so as to accommodate specific needs of the scope in which it is defined. Please describe such deviations/emphasized characteristics in this section, and which needs that helps accommodate.-->
See also: %%digital agent|digital-agent%%, and %%agent|agent%%.
......@@ -9,12 +9,12 @@ hoverText: "Transaction Result Dispatcher (TRD): a functional component that is
---
## Short Description
A **Transaction Result Dispatcher (TRD)** is a functional component that applications (that work for some %%Party%%) can call to communicate things such as:
A **Transaction Result Dispatcher (TRD)** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that applications (that work for some %%Party|party%%) can call to communicate things such as:
- the results of a business transaction (e.g. statements to confirm that a transaction happened, thereby supplying appropriate details)
- the status of a business transaction (e.g. that an order has been received in good order, that delivery of an order is dealyed or otherwise changed)
- knowledge (including judgements) that this Party has about %%Entities|entity%% (people, organizations, things, orders, deliveries, etc.)
The TRD uses a %%TRD-policy|trd-policy%% to learn about the applicable (business) rules of the %%Party%% on whose behalf it works.
The TRD uses a %%TRD-policy|trd-policy%% to learn about the applicable (business) rules of its %%principal|principal%%. Such a policy may specify e.g. which types of credentials its principal is willing to (have) issue(d), to whom such credentials may be issued and the kinds of assurances that must be obtained before doing so, etcetera.
The TRD uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities.
......@@ -22,14 +22,14 @@ The TRD uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wall
The purpose of the TRD component is to state the (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other Parties. A special kind of result is the (provisioning of) a credential that its Owner already has created.
## Criteria
A **Transaction Result Dispatcher (TRD)** is a component in the [eSSIF-Lab functional architecture](..\functional-architecture\) that is capable of stating (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other %%Parties|Party%%.
A **Transaction Result Dispatcher (TRD)** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) that is capable of stating (various, sometimes intermediary) results of transactions, by collecting data from the Business Data Stores, and creating a set of (related) statements/claims that can subsequently be issued to other %%Parties|party%%.
## Functionality
Typically, and at any point in time, Parties are capable of expressing statements about entities that they know to exist. They could express statements about individuals, about themselves, the state of transactions, and so on. We will use the term ‘**subject (of a statement of a Party)**’ to refer to the entity that this Party knows to exist, and about whom/which the statement has been made.
We will use the term ‘**subject-id (of a statement of a Party)**’ to refer to the representation that this Party has chosen to use for referring to the subject in said statement. A subject-id must have the property of being an identifier within every administrative context that this Party uses. It need not be humanly interpretable (and preferably is not).
Parties need to specify the kinds of credentials they are willing to issue, the class of entities (e.g. people, cars, Organizations) for which it will issue them, and the information schema (structure) that it will use in credentials of such kinds.<sup>[TRD.1]</sup> This allows the TRD to construct data objects that conform to this information schema, and present it to the Issuer component for actual issuing.
Parties need to specify the kinds of credentials they are willing to issue, the class of entities (e.g. people, cars, Organizations) for which it will issue them, and the information schema (structure) that it will use in credentials of such kinds.[^1] This allows the TRD to construct data objects that conform to this information schema, and present it to the Issuer component for actual issuing.
The TRD Issuing Policy specifies the kinds of (linked-)data-objects that credentials may be created for. This allows the TRD to construct such a (linked-)data-objects for every subject-id that identifies a subject of the class for which a credential can be issued, which can subsequently be sent to the Issuer component that can turn it into a credential of a specific sort.
......@@ -39,4 +39,4 @@ The TRD may either push credential data to the Issuer component, so that the Iss
-----
[TRD.1] We assume/stipulate that the Party maintains a credential catalogue that contains this, and other information about every kind of credential that it issues, and that such catalogues are available to other Parties that want or need to use such credentials.
[^1]: We assume/stipulate that the Party maintains a credential catalogue that contains this, and other information about every kind of credential that it issues, and that such catalogues are available to other Parties that want or need to use such credentials.
......@@ -9,28 +9,43 @@ hoverText: "Transaction Validation Engine (TVE): a functional component that pro
---
## Short Description
A **Transaction Validation Engine (TVE)** is a functional component that provides business applications with forms that users have filled in, and where the content of such forms is valid for making decision(s) by this application. The TVE uses a %%TVE-policy|tve-policy%% to learn about the applicable (business) rules of the %%Party%% on whose behalf the TVE works. The TVE uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities.
A **Transaction Validation Engine (TVE)** is an (architectural) function (a functional component in the [eSSIF-Lab functional architecture](../functional-architecture)) that provides business applications with forms that users have filled in, and where the content of such forms is valid for making decision(s) by this application. The TVE uses a %%TVE-policy|tve-policy%% to learn about the applicable (business) rules of the %%Party|party%% on whose behalf the TVE works.
The TVE uses a %%TVE-policy|tve-policy%% to learn about the applicable (business) rules of its %%principal|principal%%. Such policy may specify which parties can be trusted to issue credentials of a specific kind, how the contents of such credentials map onto data elements as the %%principal|principal%% needs them, etcetera.
The TVE uses the %%eSSIF-Glue|essif-glue%% interface to access the %%Wallet|wallet%%, %%Holder|holder%%, %%Issuer|issuer%% and %%Verifier|verifier%% functionalities.
## Purpose
The purpose of the Transaction Validation Engine (TVE) is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
## Criteria
A **Transaction Validation Engine (TVE)** is a component in the [eSSIF-Lab functional architecture](..\functional-architecture\) whose function is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
A **Transaction Validation Engine (TVE)** is a functional component in the [eSSIF-Lab functional architecture](../functional-architecture) that
- services requests by %%digital|digital-agent%% and non-digital %%agents|agent%%, for providing a product or service, thereby starting a %%transaction|business-transaction%%;
- can set-up and tear-down communications channels of various kinds, with %%digital|digital-colleague%% and/or non-digital %%colleagues|colleague%% of that %%requesting agent|agent%%,[^peer-agents] as appropriate for the data exchanges that are needed to conduct the transactions;
- can use any appropriate communications channel with a %%peer-agent|peer-agent%% to:
- request for data that, according to the %%tve-policy|tve-policy%% is needed to decide whether or not to commit to the transaction;
- process the responses to such requests, in an orchestrated way, thereby complying with the rules of its %%principal's|principal%% %%tve-policy|tve-policy%%, the result of which (in the end) is a set of %%validated data|validated-data%% that can serve the purpose of deciding whether or not to commit to the transaction;
- receive similar requests from its %%peer-party%%, and respond to such requests in compliance with the rules of its %%principal's|principal%% %%tve-policy|tve-policy%%;
- has a mechanism to ensure that within a %%transaction|business-transaction%%, it uses the latest (most receent) %%tve-policy|tve-policy%% of its %%principal|principal%%.
## Functionality
:::info Editor's note
TNO to revise the text below.
:::
Typically, the TVE would start a transaction either
- when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind.
- when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.<sup>[TVE.1]</sup>
- when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.[^one]
In either case, a transaction form (object, context) has to be created that matches the kind of transaction, and a ‘**transaction-id**’ must be generated that identifies this form/object/context. It will be used for binding incoming or outgoing messages to this transaction, enabling communications to remain congruent, not only with the Agent that requested the transaction, but also with other Agents from the same Owner and/or using different communications channels.
Handling/managing the various communications channels through which data can be exchanged is also a task of the TVE<sup>[TVE.2]</sup>. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens).
Handling/managing the various communications channels through which data can be exchanged is also a task of the TVE[^2]. One reason for this is that negotiating a transaction not only requires data to be acquired, but also to be provided to the peer participant. Another reason is that the peer participant may use multiple Agents to provide such data, e.g. human Agents (that might use web-browsers, social-media apps, phones, or physical visits), SSI Agents (that use the SSI infrastructure), or other electronic Agents (e.g. services that can provide data when appropriate permissions are submitted - e.g. user consent tokens).
Thus, the TVE is generally considered capable of obtaining data through different communications channels. However, the technical tracks of eSSIF-Lab will exclusively focus on the communications channel through which credentials can be requested and obtained. Any extensions or business productization of TVE designs may be considered in the business tracks of eSSIF-Lab. The latter is not considered any further in this section.
In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the TVE needs to know what kinds of credentials it should ask for, which Parties its Owner trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.<sup>[TVE.3]</sup> Also, when the TVE gets a credential that satisfies the necessary verification proofs, it needs a way to map the contents of that credential to the structure of the transaction context that is used internally by (other systems of) its Owner.<sup>[TVE.4]</sup> Also, as the TVE gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.<sup>[TVE.5]</sup>
In order to acquire data through SSI mechanisms for filling in a form for a specific kind of transaction, the TVE needs to know what kinds of credentials it should ask for, which Parties its Owner trusts to issue such credentials, what kinds of verification proofs for such credentials must hold and which may be disregarded.[^3] Also, when the TVE gets a credential that satisfies the necessary verification proofs, it needs a way to map the contents of that credential to the structure of the transaction context that is used internally by (other systems of) its Owner.[^4] Also, as the TVE gets more and more data - which it may get through multiple, different channels - it needs to determine whether or not the resulting set is sufficiently consistent and coherent.[^5]
In order to make the TVE work, a Validation Policy (or TVE Policy) is created by, or on behalf of the Owner, which specifies at least:
......@@ -39,7 +54,7 @@ In order to make the TVE work, a Validation Policy (or TVE Policy) is created by
- the criteria (business rules) that should be used to determine that the form is ‘clean’, i.e. that the necessary and sufficient data have been obtained and that they are consistent, coherent, and suitable for making a transaction commitment decision.
- the kinds of credentials and issuers that the Owner is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing Parties do the actual credential issuing may be specified<sup>[TVE.6]</sup>.
- the kinds of credentials and issuers that the Owner is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing Parties do the actual credential issuing may be specified[^6].
- for each kind of credential: the verification proofs that must hold to be accepted as a source for valid data.
......@@ -47,24 +62,27 @@ In order to make the TVE work, a Validation Policy (or TVE Policy) is created by
The Policy must be designed in such a way that it is extendable as new features will be called for in the future.
The ability to create new transaction contexts and the availability of the TVE Policy enable the TVE to request the Verifier component of its Owner to obtain credentials of the types that it can use to fill in the transaction form when they satisfy the verification and validation requirements of its Owner.<sup>[TVE.7]</sup>
The ability to create new transaction contexts and the availability of the TVE Policy enable the TVE to request the Verifier component of its Owner to obtain credentials of the types that it can use to fill in the transaction form when they satisfy the verification and validation requirements of its Owner.[^7]
When the Verifier returns such data (which comes with a list of proofs that the Verifier has checked), the TVE must then validate that data, i.e. determine whether or not it is valid for the specific transaction it is assembling the data for. The validation rules are Party-specific and hence come from the TVE policy. For simple cases, validation can simply consist of checking whether or not all verification proofs succeeded. At the other end of the validation spectrum, the TVE itself must make validation decisions, either electronically (according to the TVE policy) or by ‘outsourcing’ such decisions to human Agents of its Owner by providing an appropriate validation user interface.
As long as data is needed, the TVE can intermittently request the verifier to produce it (or it can use other communications channels, which is outside scope for now). It does so until it times out, or the form has become ‘clean’.
-----
### Notes:
[^1 (peer-agents)]: Note that such agents have then become so-called %%peer-agents|peer-agent%% (of the TVE) for that specific transaction. Also, the (single!) %%principal|principal%% of these %%peer-agents|peer-agent%% is the %%peer-party|peer-party%% of the %%principal|principal%% of the TVE (again, for that specific transaction).
[TVE.1] This feature ensures that the transaction is really two-way, and both Parties can request credentials from the other. For example, a web-shop can then ask for a (delivery) address credential, and the customer can ask for a credential issued e.g. by the chamber of commerce that the web-shop is a legitimate company (and not some maffia website).
[^1]: This feature ensures that the transaction is really two-way, and both Parties can request credentials from the other. For example, a web-shop can then ask for a (delivery) address credential, and the customer can ask for a credential issued e.g. by the chamber of commerce that the web-shop is a legitimate company (and not some maffia website).
[TVE.2] It may well be that this functionality can somehow be split off in the (near) future.
[^2]: It may well be that this functionality can somehow be split off in the (near) future.
[TVE.3] For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Owner of the TVE. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years.
[^3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the Owner of the TVE. An example from the physical world: in order to obtain a visa for China, it is required that your passport (credential) remains valid for 3 months after the end of your visit. But in order to identify yourself at the reception desk of a hotel, your passport may have expired several years.
[TVE.4] For example, a credential that contains an address uses a specific schema to specify addresses, e.g. the ‘PostalAddress’ as defined by schema.org. This schema differs quite a bit from that of Dutch addresses as [*defined*](https://bag.basisregistraties.overheid.nl/def/bag) by the official (authentic) Dutch Registration of Addresses and Buildings (BAG). It may also well differ from the structure of addresses that databases of the Owner have implemented. Mapping allows such cases to be accommodated for.
[^4]: For example, a credential that contains an address uses a specific schema to specify addresses, e.g. the ‘PostalAddress’ as defined by schema.org. This schema differs quite a bit from that of Dutch addresses as [*defined*](https://bag.basisregistraties.overheid.nl/def/bag) by the official (authentic) Dutch Registration of Addresses and Buildings (BAG). It may also well differ from the structure of addresses that databases of the Owner have implemented. Mapping allows such cases to be accommodated for.
[TVE.5] Inconsistent or incoherent data is necessary for various purposes. First, it allows for correct further processing of the transaction. A non-existent postal code, or one that doesn’t match the delivery address, may hinder a fluent transaction processing, resulting in additional costs and processing times. Another purpose is the early warning or detection of possible fraud/abuse. Remember that part of the data is being asked for reducing transaction risk, and checking consistency/coherence of such data is part of the risk mitigation process.
[^5]: Inconsistent or incoherent data is necessary for various purposes. First, it allows for correct further processing of the transaction. A non-existent postal code, or one that doesn’t match the delivery address, may hinder a fluent transaction processing, resulting in additional costs and processing times. Another purpose is the early warning or detection of possible fraud/abuse. Remember that part of the data is being asked for reducing transaction risk, and checking consistency/coherence of such data is part of the risk mitigation process.
[TVE.6] This enables the TVE to pass the endpoint URI on to the Verifier when it requests for such a credential, which in turn can send it to the holder of other Parties enabling them to obtain the credential from that issuer endpoint if that other Party does not have that credential in its wallet. The endpoint URI can in fact be put in the policy, because the (human) Agent that creates/maintains the policy would need to know that the issuing Party is actually issuing such credentials, what their contents means, etc., and hence is capable of tracking down the URI where that Party issues the credentials.
[^6]: This enables the TVE to pass the endpoint URI on to the Verifier when it requests for such a credential, which in turn can send it to the holder of other Parties enabling them to obtain the credential from that issuer endpoint if that other Party does not have that credential in its wallet. The endpoint URI can in fact be put in the policy, because the (human) Agent that creates/maintains the policy would need to know that the issuing Party is actually issuing such credentials, what their contents means, etc., and hence is capable of tracking down the URI where that Party issues the credentials.
[TVE.7] A reference to this specification will be added when it becomes available (draft or otherwise).
[^7]: A reference to this specification will be added when it becomes available (draft or otherwise).
......@@ -15,22 +15,22 @@ A **Transaction (Validation) Engine** or **TRD** is a functional component that
The purpose of the Transaction (Validation) Engine (TRD) is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
## Criteria
A **Transaction (Validation) Engine** or **TRD** is a component in the [eSSIF-Lab functional architecture](..\functional-architecture\) whos function is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
A **Transaction (Validation) Engine** or **TRD** is a component in the [eSSIF-Lab functional architecture](../functional-architecture) whos function is to produce (transaction-type specific) data structures or forms, each of which contains the necessary and sufficient data that allows (an %%agent|agent%% of) its %%owner|owner%% to decide whether or not to engage in a (new) transaction of the specified type.
## Functionality
Typically, the TRD would start a transaction either
- when it receives a request from some Agent of another Party for engaging in a transaction of a specific kind.
- when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.<sup>[TRD.1]</sup>
- when it is instructed by, or on behalf of its Owner, to request a specific kind of transaction to some Agent of another Party.[^1]