Commit b944b7ec authored by fmerg's avatar fmerg

Replace relative paths/Split functional architecture content

parent 9b3861e2
Pipeline #3214 passed with stages
in 1 minute and 32 seconds
......@@ -8,7 +8,7 @@ The eSSIF-Lab framework has an architecture which is further developed during th
This means that all eSSIF-Lab open calls are directly related to the eSSIF-Lab architecture, see Figure 1 below. This architecture will remain work in progress during the whole eSSIF-Lab project in 2020-2022.
![eSSIF-Lab Architecture](/images/eSSIF-Lab-Architecture.png)
![eSSIF-Lab Architecture](https://essif-lab.pages.grnet.gr/essif-lab/images/eSSIF-Lab-Architecture.png)
*Figure 1: eSSIF-Lab architecture*
......
---
id: detailed_transaction_flows
title: Detailed Transaction Flows
sidebar_label: Detailed transaction flows
---
**this section is being constructed now (it is only for the very curious to read...)**
This chapter explains the details of how electronic business transactions are being conducted using the eSSIF-Lab architectural components as described in chapter 2. We keep on using the parking permit example that we introduced in section 1.1. for illustrative purposes.
Note that both parties, requester and provider, each have components as described in chapter 2. Also note that whenever we introduce another party, it too has such components. Thus, every party can play any of the traditional SSI roles ‘verifier’, ‘holder’ and ‘issuer’, and each has its own ‘wallet’ functionality. Also, they all have TVE and TRD functionality that connect these aforementioned infrastructural components with the business applications.
When reading the next sections, please be aware that when a component of one of these parties communicates with another component, this other component may be of the same party, as well as of the other party. Figure 2 only shows components that belong to a single party.
### 6.1. Starting a Transaction
The requester starts the transaction by pointing his web-browser to a web-page of the provider that (a) explains how to get a parking permit, and (b) provides a parking-permit application form that needs to be filled in. Technically, this means that the browser does a GET request to an endpoint that is serviced by the providers TVE component.
The TVE services this request by creating an empty form of a type appropriate for the request. Then, it continues with requesting data to fill in the form (and providing data as requested by the other party). It starts this by providing a web page that includes the form to be filled in, as well as a deep-link, QR-code or something similar that allows the requester’s browser (plug-in) or SSI-app to contact the provider-endpoint and set up a secure communications channel through which both can communicate electronically. From then on there are two channels between the requester and the provider: one is a traditional (manual) web-browser - web-server channel, the other is one within which the SSI-agent components of various parties will be communicating.
It is a task of the TVE to orchestrate the inputs: different parts of the form may be filled in and subsequently changed in different ways. Some parts
- are required only after a certain condition is met (which is to be evaluated whenever the data that is entered into the form is changed)
- must or may initially be filled in manually (i.e.: through the browser);
- must or may initially be filled in with data from a credential;
- may be changed manually;
- may be changed with data from a newly supplied credential.
Because of this orchestration, the interface to the verifier component can be quite simple; it is shown in the image below:
![Generic Verification with SSI service](https://essif-lab.pages.grnet.gr/essif-lab/images/Generic Verification with SSI service.png)
The request identifier is included in messages between the TVE and verifier so as to allow them to handle different transactions at the same time.
We assume that the provider has specified the form and the associated validation- and issuing policies that make the following description work. We refer the reader to section \[tbd\] for an explanation of how the provider can do this.
### 6.2. Stating a Transaction
[text still needs to be written\]
![Generic Issuing with SSI service](https://essif-lab.pages.grnet.gr/essif-lab/images/Generic Issuing with SSI service.png)
......@@ -4,7 +4,7 @@ title: Functional Architecture
sidebar_label: Functional architecture
---
<p align="center"><img src="images/EU-flag.jpg" height="80" /> <img src="images/eSSIF-Lab logo.png" height="80" /></p>
<!-- <p align="center"><img src="images/EU-flag.jpg" height="80" /> <img src="images/eSSIF-Lab logo.png" height="80" /></p> -->
eSSIF-Lab is funded by the European Commission, as part of the Horizon 2020 Research and Innovation Programme, under Grant Agreement Nº 871932 and it’s framed under[ ](http://ngi.eu/)[*Next Generation Internet Initiative*](http://ngi.eu/).
......@@ -43,7 +43,7 @@ However, the participants of a business transaction are different parties, which
Every agent that communicates with another actor for the purpose of progressing a transaction, will need to be sufficiently sure (to the extent necessary for the value of the transaction) that the actor that it is communicating with, is in fact an agent of the peer party of its owner. We will use the term ‘**peer agent (of a specific agent, in the context of a single transaction)**’ to refer to an actor with which the specific agent has a communications session, and for which it has obtained sufficient assurance that it is an agent of the peer party of its owner. Note that establishing whether or not an actor is a peer agent does not necessarily require knowing who the peer party actually is.
![eSSIF-Lab Single Party Functional Architecture Overview](images/eSSIF-Lab-Architecture.png)
![eSSIF-Lab Single Party Functional Architecture Overview](https://essif-lab.pages.grnet.gr/essif-lab/images/eSSIF-Lab-Architecture.png)
*Figure 1. eSSIF-Lab Single Party Functional Architecture Overview.*
......@@ -115,7 +115,7 @@ The **SSI Tech APIs** interface layer is the union of the interfaces that the co
This section details the functional specifications of the components that are in scope of the eSSIF-Lab infrastructure, i.e. in the green (rounded) rectangle as shown in the figure below:
![eSSIF-Lab functional components that are part of the eSSIF-Lab infrastructure](images/eSSIF-Lab-architecture-infra-components.png)
![eSSIF-Lab functional components that are part of the eSSIF-Lab infrastructure](https://essif-lab.pages.grnet.gr/essif-lab/images/eSSIF-Lab-architecture-infra-components.png)
*Figure 2: eSSIF-Lab infrastructural (functional) components.*
......@@ -382,7 +382,7 @@ It is a task of the TVE to orchestrate the inputs: different parts of the form m
Because of this orchestration, the interface to the verifier component can be quite simple; it is shown in the image below:
![Generic Verification with SSI service](images/Generic Verification with SSI service.png)
![Generic Verification with SSI service](https://essif-lab.pages.grnet.gr/essif-lab/images/Generic Verification with SSI service.png)
The request identifier is included in messages between the TVE and verifier so as to allow them to handle different transactions at the same time.
......@@ -392,4 +392,4 @@ We assume that the provider has specified the form and the associated validation
[text still needs to be written\]
![Generic Issuing with SSI service](images/Generic Issuing with SSI service.png)
![Generic Issuing with SSI service](https://essif-lab.pages.grnet.gr/essif-lab/images/Generic Issuing with SSI service.png)
<!-- <p align="center"><img src=".\images\EU-flag.jpg" style="zoom:5%;" /> <img src=".\images\eSSIF-Lab logo.png" style="zoom:75%;" /></p> -->
eSSIF-Lab is funded by the European Commission, as part of the Horizon 2020 Research and Innovation Programme, under Grant Agreement Nº 871932 and it’s framed under[ ](http://ngi.eu/)[*Next Generation Internet Initiative*](http://ngi.eu/).
# eSSIF-Lab Vision and Purpose
<p align="center">Author: Rieks Joosten (TNO)</p>
......
......@@ -41,7 +41,7 @@ Figure 1 is explained in more detail in the (living) document “[eSSIF-Lab Visi
Figure 2 sketches relationships between the open calls.
![Relationship among eSSIF-Lab open calls](/images/Relationship-among-eSSIF-Lab-open-calls.png)
![Relationship among eSSIF-Lab open calls](https://essif-lab.pages.grnet.gr/essif-lab//images/Relationship-among-eSSIF-Lab-open-calls.png)
Figure 2: Relationships between the eSSIF-Lab open calls
......
---
id: high_level_transaction_flows
title: High Level Transaction Flows
sidebar_label: High level transaction flows
---
This chapter explains at a high level how electronic business transactions are being conducted. This is prerequisite to the explanations in chapter 4, that describe how the eSSIF-Lab architectural components are used in such transactions. For illustrative purposes, we stick to the example of getting a parking permit that we introduced in section 1.1.
### 5.1. Overview
<center><img src="images/eSSIF-Lab - high level trx overview.png" alt="eSSIF-Lab - high level trx overview" height="200"/></center>
The adjacent figure shows how a transaction is conducted at the highest abstraction level. One party, called the ‘Requester’, sends a request for a product or service to another party (that we will call the ‘Provider’). Then, they start to negotiate a ‘transaction agreement’, which means that they exchange data through various channels for the purpose of establishing the details of the product/service to be provided and the compensation, data needed to mitigate transaction risks, etc., all of which is necessary for the parties to (individually/subjectively) decide whether or not to commit to the transaction. Section 3.2 provides more detail about this phase.
After commitment, the producer works to provide the product or service, and the requester arranges the compensation. This phase is entirely up to the business, and hence out of scope of this document.
When all is done, parties may issue a (signed) statement that specifies the results. Section 3.3. provides some more details about this phase.
In the example of the parking permit, a citizen (requester) sends a request to its municipality (provider) for obtaining a parking permit (the product/service). Then, the citizen fills in an online form (and uploads necessary PDFs) to enable the municipality to decide whether or not to produce the requested permit. The eSSIF-lab architecture adds a secondary, electronic channel that allows citizens to fill in the forms by using e.g. an SSI app on their phone. When the form is complete, the municipality decides whether or not to produce and issue the permit, which it can do as usual. It can also issue a credential that states the result of the transaction, i.e. contains the details of the parking permit.
Please note that while transactions are symmetrical in nature (i.e. both requester and provider need data from the other so as to decide whether or not to commit to the transaction), there is an implicit asymmetry in that activities that parties perform are ordered in time, which implies e.g. that the commitment decisions of both parties cannot be done at the same time. Also, in practice, it often happens that a party requires the other party to have executed (and stated) its part of the transaction before it actually commits to the transaction. For example, a provider may require the requester to have paid for the product before it is being shipped out. Consequently, the protocols for exchanging data/credentials will need to support such ‘asynchronous’ ways of working.
### 5.2. Transaction Negotiation Phase
This phase starts by the requester sending a transaction request to the provider, and ends whenever either one of the parties quits, or both parties commit.
<img src="images/eSSIF-Lab - high level trx negotiation.png" alt="eSSIF-Lab - high level trx negotiation" height="250"/>
The adjacent figure shows the high-level interactions during this phase. It starts by the requester sending a request for a product or service to the provider. Typically, this would lead to the provider presenting a (web) form the requester must fill in. In the eSSIF-Lab context, the form will also provide a means for setting up a SSI communications channel, i.e. a secure communications channel through which provider and requester can both request and obtain (presentations of) credentials, the contents of which they can use to fill in the form. Then, after the form is ‘clean’, i.e. contains sufficient information for deciding whether or not to commit to the transaction, this phase ends.
Note that forms may contain fields that are required only in specific circumstances. It may only be possible to assess whether or not such circumstances apply after some (other) fields have been filled in. This means that the phase for requesting credential presentations and responding to such requests may very well consist of multiple requests and associated responses.
In the example of the parking permit, the municipality might ask for a credential that proves the requester is a citizen that is a registered inhabitant of said municipality, a credential stating its residential address, a credential stating the make and license plate of the vehicle for which a parking permit is requested, etc. All this is subject to the policy that the municipality has established for issuing such permits, and hence, it must be expected to differ between municipalities.
An example of conditionally required fields would be when the requester wants the municipality to customize the parking lot, e.g. because the requester has disabilities. Assessing such circumstances depends on the (optional) field where the requester must state any disabilities it has, and when that is the case, the requester may be asked to fill in fields such as whether or not a parking lot has to be customized (painted blue, with a sign stating that it is reserved for the provided license-place, or the kind of charging device if (s)he has an electric vehicle).
Conversely, the citizen might request the (alleged) municipality to provide credentials, e.g. to prove that it is actually an official municipality of the country it is part of. This would provide assurance to the citizen that it would actually be paying the fees to that municipality rather than to e.g. a rogue organization that might have spoofed the website of the municipality.
### 5.3. Stating Transactions - Issuing Credentials
In the eSSIF-Lab context, we take ‘credential’ to mean any (set of coherent) statement(s) about any (one or more) subject(s) that a single party has issued with proof of provenance (i.e. anyone else can determine the identity of that issuer) and a proof of integrity (i.e. anyone can determine whether or not the content of the credential has been changed/tampered with since it was issued). From this, it follows that any party can issue any kind of credential for any entity that it knows to exist. A credential does not need to be about a person or an organization, but it can also refer to an order, a delivery, a seat-reservation, a prescription, etc.
We foresee two ways in which credentials can be issued:
1. both the requester and provider may issue credentials to the other party in the process flow that they are in. They can do so for the purpose of stating any (lack of) progress and/or results of the administrative process flow they are in.
In the example of the parking permit, the municipality may need some time to do some manual checks before it can issue the permit; in this case, it could issue a credential that states that the citizen has requested the parking permit and any other details that might be appropriate. Also, if it can issue the parking permit straight away, it can issue a credential that contains the details of that permit. The requester may issue a credential to the municipality stating the date/time and kind of transaction, judgements or comments about the service that the municipality has provided.
2. any party may issue a credential upon request. Basically, this means that a party (in the role of requester) issues a request to that other party (in the role of provider) asking for the particular credential. This is just another case of doing transactions, that can be handled just as any other kind of transaction.
In the example of the parking permit, when a citizen requests a permit, the provider might look for an existing permit prior to issuing a new one (it would have to do such a check during the process anyway), and depending on its business logic it would be providing the credential without further ado, or start the process of issuing a new one.
This diff is collapsed.
---
id: motive
title: Motive
sidebar_label: Motive
---
The purpose of the functional architecture and its views is to
- **provide mental models** that all of its stakeholders interpret in sufficiently the same way, so as to be able to talk, think and discuss about what it is we try to achieve and ways to achieve this;
- help **inventory and subsequently address any (other) concerns and issues** of every one of its stakeholders;
- help **achieve interoperability** both at the technical and at the business levels.
---
id: network_architecture
title: Initial SSI-Agent Network Architecture
sidebar_label: Network architecture
---
The SSI-Agent Network Architecture has two viewpoints:
1. the **intra-party or single-party SSI viewpoint**, which focuses on the set of (human and/or electronic) agents of a single, specific party.
2. the **inter-party or multi-party SSI viewpoint**, which is about specific functional components (e.g. Verifier, Holder, etc.) that typically belong to different parties.
An individual party may use the single-party SSI viewpoint to come to grips with concerns related to the creation and maintenance of its network of its electronic agents. The set of concerns would include:
- How can electronic components be onboarded as an agents of this party?
- How can the integrity of such electronic agents be stated in a trustworthy manner (do such components need some kind of accreditation certificate, do we need to come up with a service that can remotely test the integrity of a component and have it issue ephemeral integrity-certificates/credentials, …)?
- How can the party specify which of its agents may talk with which other agents, and for what purposes?
- How should a party specify the policies for the various SSI functionalities - what kind of support would be useful here?
-
Parties that want (their agents) to interact with one another may use the multi-party SSI viewpoint to come to grips with concerns related to the interoperability of the functionalities that their components implement. The set of concerns would include:
- How can parties interact with one another at the information level (this includes decentralized semantic interoperability issues, advertising credentials, how a party can find other parties that issue credentials that are useful to him, etc.)
- What kinds of underlying technologies must agents of a party support so as to be(come) interoperable with parties that it wants to interact with?
-
......@@ -14,7 +14,7 @@ The eSSIF-Lab framework is an SSI-domain-specific [software framework](https://e
Figure 2 sketches relationships between the open calls.
![Relationship among eSSIF-Lab open calls](/images/Relationship-among-eSSIF-Lab-open-calls.png)
![Relationship among eSSIF-Lab open calls](https://essif-lab.pages.grnet.gr/essif-lab/images/Relationship-among-eSSIF-Lab-open-calls.png)
Figure 2: Relationships between the eSSIF-Lab open calls
......
This diff is collapsed.
---
id: terminology
title: Basic Terminology
sidebar_label: 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**’ for that) and people and ‘things’ that are capable of acting/doing things (we will use the term ‘**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.
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**’ for or of that party (at that particular point in time). We say that this actor acts ‘**on behalf of**’ that party. When an SSI component acts as an agent for/on behalf of some party, we call it an \`**SSI-agent**\`, and we say that this party is the ‘**owner**’ of that component. Also, we use the term \`**(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.
Given these definitions, it is obvious that parties are not necessarily capable of acting. However, we also would like to be able to generically use phrases such as ‘party X does Y’. To this end we introduce the term \`**organization**\` as the collection of one specific party and every of its agents, and when we say ‘party X does Y’, we mean to say that there is an agent that does Y, where that agent belongs to the same organization as the specified party..
We caution that the notions of being an ‘agent’, ‘owner’, ‘colleague’, and being part of an ‘organization’ are dynamic; they may frequently change over time and are never self-evident.
Also, to serve the aforementioned purposes, we cannot fix the architecture (and the fact that eSSIF-Lab is an experimentation environment already implies this). We see it is a first attempt to describe an architecture that will be regularly updated as we - i.e. the eSSIF-Lab consortium and all subgrantees and perhaps some others - work together as an ecosystem-in-formation to realize the aforementioned vision.
......@@ -13,7 +13,8 @@ module.exports = {
src: 'images/eSSIF-Lab logo.png',
},
links: [
{to: 'docs/introduction', label: 'Introduction', position: 'left'},
{to: 'docs/essif-lab-vision-and-purpose', label: 'Vision', position: 'left'},
{to: 'docs/introduction', label: 'Quick intro', position: 'left'},
{
href: 'https://gitlab.grnet.gr/essif-lab/essif-lab',
label: 'Gitlab',
......@@ -41,19 +42,19 @@ module.exports = {
},
],
},
{
title: 'Community',
items: [
{
label: 'Stack Overflow',
href: 'https://stackoverflow.com/questions/tagged/docusaurus',
},
{
label: 'Discord',
href: 'https://discordapp.com/invite/docusaurus',
},
],
},
// {
// title: 'Community',
// items: [
// {
// label: 'Stack Overflow',
// href: 'https://stackoverflow.com/questions/tagged/docusaurus',
// },
// {
// label: 'Discord',
// href: 'https://discordapp.com/invite/docusaurus',
// },
// ],
// },
{
title: 'Social',
items: [
......
module.exports = {
sidebar_1: {
// 'Vision and Purpose':
// [
// 'essif-lab-vision-and-purpose',
// ],
'Framework':
[
'introduction',
......@@ -12,7 +8,13 @@ module.exports = {
],
'Functional Architecture':
[
'functional_architecture',
'motive',
'terminology',
'overview',
'infrastructure',
'network_architecture',
'high_level_transaction_flows',
'detailed_transaction_flows'
]
},
};
......@@ -17,59 +17,6 @@ const features = [
</>
),
},
// {
// title: <>Use Git and Gitlab</>,
// imageUrl: 'img/undraw_Tree_swing.svg',
// description: (
// <>
// How we work with git and gitlab (basic workflow, MRs, pre-commit hooks
// etc.).
// </>
// ),
// },
// {
// title: <>Work as a Team</>,
// imageUrl: 'img/undraw_co-working.svg',
// description: (
// <>
// How we collaborate as a team (scrum, agile, retrospectives, weekly
// meetings etc). How we apply best practices to our daily life.
// </>
// ),
// },
// {
// title: <>Easy to Use</>,
// imageUrl: 'images/eSSIF-Lab icon.png',
// description: (
// <>
// Docusaurus was designed from the ground up to be easily installed and
// used to get your website up and running quickly.
// </>
// ),
// },
// {
// title: <>Horizon 2020</>,
// imageUrl: 'images/EU-flag.jpg',
// description: (
// <>
// Funded by the European Commission, as part of the Horizon 2020 Research
// and Innovation Programme.
// </>
// ),
// },
// ---------------------------------------------------------------------------
//
// {
// title: <>Powered by React</>,
// imageUrl: 'img/undraw_docusaurus_react.svg',
// description: (
// <>
// Extend or customize your website layout by reusing React. Docusaurus can
// be extended while reusing the same header and footer.
// </>
// ),
// },
];
function Feature({imageUrl, title, description}) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment