Commit 0642d3eb authored by Rieks Joosten's avatar Rieks Joosten

update and test %-selection regexes

parent 22d9fe9b
Pipeline #16884 passed with stage
in 2 minutes and 8 seconds
......@@ -15,3 +15,4 @@ start_server.bat
*.lnk
docs/vscode-%%-batch-replacer.txt
**/zzz-*
docs/test.md
......@@ -26,9 +26,9 @@ Figure 1 shows the initial *functional* eSSIF-Lab architecture, and its scope, c
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 issuer, 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*.
Since the participants of a business transaction are different parties, the negotiation, commitment and execution of that transaction will be done by agents of these different parties. Assuming that a single transaction has two such parties, we will use the term ‘Peer Party (of a specific Party, in the context of a single transaction)’ to refer to the participating party in that transaction that is not the specific %%party|party%% itself.
Since the participants of a business transaction are different parties, the negotiation, commitment and execution of that transaction will be done by agents of these different parties. Assuming that a single transaction has two such parties, we will use the term ‘Peer Party (of a specific Party, in the context of a single transaction)’ to refer to the participating party in that transaction that is not the specific party itself.
When an %%agent|agent%% is involved in such a transaction, it will be communicating with a component that it assumes to be an %%agent|agent%% of the %%Peer Party|peer-party%% of its %%principal|principal%% (the %%agent|agent%% may obtain further assurances for that, but that's outside the scope for now). We will use the term ‘%%Peer Agent (of a specific Agent, in the context of a single transaction)|peer-agent%%’ to refer to an %%actor|actor%% with which the specific %%agent|agent%% has a %%communication session|communication-session%%. Note that establishing whether or not an %%actor|actor%% is a %%Peer Agent|peer-agent%% does not necessarily require knowing who the %%Peer Party|peer-party%% actually is.
When an agent is involved in such a transaction, it will be communicating with a component that it assumes to be an agent of the Peer Party of its principal (the agent may obtain further assurances for that, but that's outside the scope for now). 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 communication session. Note that establishing whether or not an %%actor|actor%% is a %%Peer Agent|peer-agent%% does not necessarily require knowing who the %%Peer Party|peer-party%% actually is.
The figure below is an overview of the most important *functional* components that any %%party|party%% needs to conduct electronic %%business transactions|business-transaction%%.
......@@ -39,7 +39,7 @@ The figure below is an overview of the most important *functional* components th
*Figure 1. eSSIF-Lab Single Party Functional Architecture Overview.*
We use the following coloring conventions in this figure: red is business related, which means that we do not consider this to be part of the SSI Infrastructure. Brown is used for policies, which are defined by (or on behalf) of the principal of the component that uses them to configure themselves, and/or act according to the %principal’s preferences and policies. Green is used for generic SSI infrastructure related functions, and blue represents functions that may be implemented as ‘plug-ins’ for specific SSI-related technologies.
We use the following coloring conventions in this figure: red is business related, which means that we do not consider this to be part of the SSI Infrastructure. Brown is used for policies, which are defined by (or on behalf) of the principal of the component that uses them to configure themselves, and/or act according to the principal’s preferences and policies. Green is used for generic SSI infrastructure related functions, and blue represents functions that may be implemented as ‘plug-ins’ for specific SSI-related technologies.
The remainder of this chapter describes the layers and their components at a high abstraction level. <!--Further details on components, such as design decisions, can be found in \[reference\].-->
......@@ -51,7 +51,7 @@ The top layer (in the red rounded rectangle) has the functions of actual busines
The lower business layer contains two functional components, one for initiating transactions and the other for stating transaction results (as per the [*DEMO*](https://en.wikipedia.org/wiki/Design_%26_Engineering_Methodology_for_Organizations) method), each of which with an associated business policy that contains business-specific policies/preferences.
The task of the Data Collector (or Data Collector) is to handle and initiate requests from/to peer agents to engage in some kind of transaction, by negotiating and exchanging data (through one or more, physical or electronic communication channels%), and to produce a transaction form whose contents are complete and valid, enabling an appropriate Colleague to decide whether or not to engage in the transaction. Note that negotiating a transaction has two parts: requesting a peer agent to provide data that its principal needs, and providing data on behalf of its principal that a peer agent requests. After all, a business transaction can only start after all %%parties|party%% have decided to commit, which they can only do after each of them has obtained the information it (subjectively) needs to do so. Also note that data that the %%data collector|data-collector%% must ensure that the transaction context is properly maintained if it chooses to exchange data through different %%communication channels|communication-channel%%.
The task of the Data Collector (or Data Collector) is to handle and initiate requests from/to peer agents to engage in some kind of transaction, by negotiating and exchanging data (through one or more, physical or electronic communication channels), and to produce a transaction form whose contents are complete and valid, enabling an appropriate Colleague to decide whether or not to engage in the transaction. Note that negotiating a transaction has two parts: requesting a peer agent to provide data that its principal needs, and providing data on behalf of its principal that a peer agent requests. After all, a business transaction can only start after all parties have decided to commit, which they can only do after each of them has obtained the information it (subjectively) needs to do so. Also note that data that the data collector must ensure that the transaction context is properly maintained if it chooses to exchange data through different %%communication channels|communication-channel%%.
The task of the %%data discloser|data-discloser%% (or %%data discloser|data-discloser%%) 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|party%%. Since such state-data may change, issuing data that supersedes an earlier state implies the revocation of such a state.
......@@ -65,11 +65,11 @@ Apart from each having a specific task, as described below, implementations that
The **issuer** functionality includes the issuing of what we will generically call '%%credentials|credential%%', i.e. sets of (related) statements/claims (e.g. as produced by the %%data discloser|data-discloser%%) that have metadata (e.g. date of issuing) and a digital signature by which third %%parties|party%% can prove its provenance and integrity. Another function of the %%issuer|issuer%% is to handle revocation (and (un)suspension) of %%credentials|credential%% that it has issued. For such tasks, it relies on functions that are made available by the SSI Protocols and Crypto Layer.
The **wallet** functionality includes the (secure) storage of %%credentials|credential%% - both those that have been issued by the %%issuer|issuer%% (i.e. self-signed %credentials) and those that have been obtained from %%issuers|issuer%% of other %%parties|party%%. Another task of the %%wallet|wallet%% is to (securely) store (private) keys that can be used to sign or seal data on behalf of its %%principal|principal%%. Perhaps the most important task of the %%wallet|wallet%% is to ensure that %%credentials|credential%% and keys can only become available to another component if they have the same (single) %%principal|principal%%, and will become available if such other component implements a functionality that needs it.
The **wallet** functionality includes the (secure) storage of %%credentials|credential%% - both those that have been issued by the %%issuer|issuer%% (i.e. self-signed %%credentials|credential%%) and those that have been obtained from %%issuers|issuer%% of other %%parties|party%%. Another task of the %%wallet|wallet%% is to (securely) store (private) keys that can be used to sign or seal data on behalf of its %%principal|principal%%. Perhaps the most important task of the %%wallet|wallet%% is to ensure that %%credentials|credential%% and keys can only become available to another component if they have the same (single) %%principal|principal%%, and will become available if such other component implements a functionality that needs it.
The **verifier** functionality is to support the %%data collector|data-collector%% as it tries to acquire %%credentials|credential%% from some other %%party|party%% for the purpose of negotiating a business transaction. It does so by creating %%Presentation Requests|presentation-request%% (or Presentation Definition as it is called in the [draft DIF specfication for Presentation Exchange](https://identity.foundation/presentation-exchange)) that ask for such %%credentials|credential%%, sending them to a %%holder|holder%% component of another %%party|party%%, receiving a response to such a request (which we call a ‘%Presentation’), verifying the %%Presentation|presentation%%, i.e. checking the signature and other proofs of the veracity of both the construction of the %%Presentation|presentation%% as well as its contents, thus providing the %%Data Collector|data-collector%% with verified data.
The task of the **holder** is to handle %%Presentation|presentation%% Requests that it receives from %%verifier|verifier%% components (both of its %%principal|principal%%, and of other %parties). Typically, this means looking for the requested data in the %principal’s %%wallet|wallet%%, and using it to construct a %%Presentation|presentation%% (=response). However, if the %%wallet|wallet%% doesn’t have it, the %%holder|holder%% may negotiate a transaction with a component of the designated %%issuer|issuer%% for the purpose of obtaining the needed %%credential|credential%%, which - when obtained - it can subsequently store in the %%wallet|wallet%% and use in the %%presentation|presentation%%.
The task of the **holder** is to handle %%presentation requests|presentation-request%% that it receives from %%verifier|verifier%% components (both of its %%principal|principal%%, and of other %%parties|party%%). Typically, this means looking for the requested data in the %%principal’s|principal%% %%wallet|wallet%%, and using it to construct a %%Presentation|presentation%% (=response). However, if the %%wallet|wallet%% doesn’t have it, the %%holder|holder%% may negotiate a transaction with a component of the designated %%issuer|issuer%% for the purpose of obtaining the needed %%credential|credential%%, which - when obtained - it can subsequently store in the %%wallet|wallet%% and use in the %%presentation|presentation%%.
### 2.3. SSI Protocols and Crypto Layer
......@@ -123,7 +123,7 @@ The purpose of the %%data collector|data-collector%% is to produce (transaction-
Typically, the %%data collector|data-collector%% would start a transaction either
- when it receives a request from some %%agent|agent%% of another %%party|party%% for engaging in a transaction of a specific kind.
- when it is instructed by, or on behalf of its %%principal|principal%%, to request a specific kind of transaction to some %%agent|agent%% of another %party.[^DC.1]
- when it is instructed by, or on behalf of its %%principal|principal%%, to request a specific kind of transaction to some %%agent|agent%% of another %%party|party%%.[^DC.1]
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|agent%% that requested the transaction, but also with other %%agents|agent%% from the same %%principal|principal%% and/or using different %%communication channels|communication-channel%%.
......@@ -142,7 +142,7 @@ In order to make the %%data collector|data-collector%% work, a %%Validation Poli
- the kinds of %%credentials|credential%% and %%issuers|issuer%% that the %%principal|principal%% is willing to accept as sources for valid data; (optionally?), the endpoint URI at which issuing %%parties|party%% do the actual %%credential|credential%% issuing may be specified[^DC.6].
- for each kind of %credential: the verification proofs that must hold to be accepted as a source for valid data.
- for each kind of %%credential|credential%%: the verification proofs that must hold to be accepted as a source for valid data.
- the mapping between fields in such %%credentials|credential%% and fields in the form to be filled in.
......@@ -160,7 +160,7 @@ As long as data is needed, the %%data collector|data-collector%% can intermitten
[^DC.2]: It may well be that this functionality can somehow be split off in the (near) future.
[^DC.3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the %%principal|principal%% of the %%data collector|data-collector%%. 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.
[^DC.3]: For high-value transactions, verification proofs are more important than for low-value transactions. This is to be decided by the %%principal|principal%% of the %%data collector|data-collector%%. An example from the physical world: in order to obtain a visa for China, it is required that your passport (%%credential|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.
[^DC.4]: For example, a %%credential|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 %%principal|principal%% have implemented. Mapping allows such cases to be accommodated for.
......@@ -176,34 +176,34 @@ As long as data is needed, the %%data collector|data-collector%% can intermitten
The purpose of the %%verifier|verifier%% component is to support the %%data collector|data-collector%% by providing it with a single, simple API that it can use to request and obtain data that it needs to produce a clean transaction form, as well as the results of checking verification proofs (this is also why it is called the ‘%verifier’ component).
Typically, the %%data collector|data-collector%% would ask the %%verifier|verifier%% to provide a %%credential|credential%% that it can use to fill in a (coherent set of) field(s) in the transaction form. It is realistic to think that %%credentials|credential%% from different %%issuers|issuer%% - trusted by the %verifier’s %%principal|principal%% - can be used for this purpose. However, it is also realistic that such %%credentials|credential%% will not use the same %%credential type|credential-type%% - they might well use different schemes to provide such data. Therefore, the %%data collector|data-collector%% should specify a list of pairs (%credential-type%, %issuer) instances of which could all be used to provide the data it needs - which it can obtain from the %%data collector policy|data-collector-policy%%.
Typically, the %%data collector|data-collector%% would ask the %%verifier|verifier%% to provide a %%credential|credential%% that it can use to fill in a (coherent set of) field(s) in the transaction form. It is realistic to think that %%credentials|credential%% from different %%issuers|issuer%% - trusted by the %%verifier’s|verifier%% %%principal|principal%% - can be used for this purpose. However, it is also realistic that such %%credentials|credential%% will not use the same %%credential type|credential-type%% - they might well use different schemes to provide such data. Therefore, the %%data collector|data-collector%% should specify a list of pairs (%%credential-type|credential-type%%, %%issuer|issuer%%) instances of which could all be used to provide the data it needs - which it can obtain from the %%data collector policy|data-collector-policy%%.
Then, the %%verifier|verifier%% needs to know the address and protocol that it can use to reach a %%holder|holder%% component owned by the %%party|party%% that its %%principal|principal%% is trying to negotiate the transaction with. The %%data collector|data-collector%% specifies this as part of the request - and it can do so because it has received the original request, and does all %%communication channel|communication-channel%% handling.
%%verifiers|verifier%% are not expected to handle every kind of %%credential|credential%% (e.g. VC’s, ABC’s, etc.) that exists, but rather a specific subset. For (at least one of) the %%credential types|credential-type%%, the %%verifier|verifier%% can construct a so-called %%presentation request|presentation-request%%, i.e. a message that is specific for the %%credential type|credential-type%% and/or associated protocol, which it can then send to the %holder’s address.
%%verifiers|verifier%% are not expected to handle every kind of %%credential|credential%% (e.g. VC’s, ABC’s, etc.) that exists, but rather a specific subset. For (at least one of) the %%credential types|credential-type%%, the %%verifier|verifier%% can construct a so-called %%presentation request|presentation-request%%, i.e. a message that is specific for the %%credential type|credential-type%% and/or associated protocol, which it can then send to the %%holder’s|holder%% address.
This request message should contain at least
- the transaction-id, so that when it is copied into the associated response message, the latter can be associated to the transaction it belongs to. Also, it should contain the
- the (%credential type%, %issuer) pairs that may satisfy the request, and to each of these additional data, e.g. the URI of the endpoint where the %%issuer|issuer%% issues such %%credentials|credential%%, the maximum age of the %%credential|credential%%, etc.
- meta-data that may be useful for the %%holder|holder%% (or its %principal), e.g. texts stating the purpose(s) for which the data will be used ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 5.1.b), or requesting consent ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 7.2) “in an intelligible and easily accessible form, using clear and plain language”.
- a signature of the %%verifiers|verifier%% %%principal|principal%%, for the purpose of showing compliance with the [*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) (e.g. Art 28.3.h), and enabling the %holder’s %%principal|principal%% to obtain proof that the %%verifiers|verifier%% %%principal|principal%% has violated the [*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN)’s minimization principle asked for data for a particular purpose, which can be used in an argument in disputes about data minimization ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 5.1.c).
- the (%%credential type|credential-type%%, %%issuer|issuer%%) pairs that may satisfy the request, and to each of these additional data, e.g. the URI of the endpoint where the %%issuer|issuer%% issues such %%credentials|credential%%, the maximum age of the %%credential|credential%%, etc.
- meta-data that may be useful for the %%holder|holder%% (or its %%principal|principal%%), e.g. texts stating the purpose(s) for which the data will be used ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 5.1.b), or requesting consent ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 7.2) “in an intelligible and easily accessible form, using clear and plain language”.
- a signature of the %%verifiers|verifier%% %%principal|principal%%, for the purpose of showing compliance with the [*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) (e.g. Art 28.3.h), and enabling the %%holder’s|holder%% %%principal|principal%% to obtain proof that the %%verifiers|verifier%% %%principal|principal%% has violated the [*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN)’s minimization principle asked for data for a particular purpose, which can be used in an argument in disputes about data minimization ([*GDPR*](https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX:32016R0679&from=EN) Art. 5.1.c).
The request message must be designed in such a way that it is extendable as new features will be called for in the future.
In order to make the %%verifier|verifier%% component work, a %%Verifier|verifier%% Policy%/Preferences object is created by, or on behalf of the %%principal|principal%%, which specifies at least: \[to be elaborated\]
A response to this request (called a %presentation) will be obtained from a %%holder|holder%% component of the %%peer party|peer-party%%. This response will contain a reference to the request, allowing the %%verifier|verifier%% to combine them. The %%verifier|verifier%% will then check that the data in the response is a %%credential|credential%% that it has asked for (correct type/%issuer), verify the proofs that are provided (predominantly the digital signature), and do some additional checks (e.g. whether or not the %%credential|credential%% has expired, is revoked, and such).
A response to this request (called a %%presentation|presentation%%) will be obtained from a %%holder|holder%% component of the %%peer party|peer-party%%. This response will contain a reference to the request, allowing the %%verifier|verifier%% to combine them. The %%verifier|verifier%% will then check that the data in the response is a %%credential|credential%% that it has asked for (correct type/%%issuer|issuer%%), verify the proofs that are provided (predominantly the digital signature), and do some additional checks (e.g. whether or not the %%credential|credential%% has expired, is revoked, and such).
Then, the %%verifier|verifier%% will send a message to the %%data collector|data-collector%%, containing the transaction-id, the data it has received, and the results of the various checks.
### 3.3. Holder Component, and its Policy/Preferences
The purpose of the %%holder|holder%% component is to handle %%Presentation Requests|presentation-request%% that it receives from %%verifier|verifier%% components (both of its own %%principal|principal%%, and of other %parties), and responding to such requests.
The purpose of the %%holder|holder%% component is to handle %%Presentation Requests|presentation-request%% that it receives from %%verifier|verifier%% components (both of its own %%principal|principal%%, and of other %%parties|party%%), and responding to such requests.
Typically, a %%holder|holder%% component would access its %%principal's|principal%% %%wallet|wallet%% to check if it has a %%credential|credential%% that it can use to construct a %%presentation|presentation%% (i.e. response) that satisfies the received request.
It may happen that the %%wallet|wallet%% does not have such a %%credential|credential%%. However, for every (%credential, %issuer) pair, the request should specify the URI that is capable of issuing such a %%credential|credential%%. If or when the %%Holder|holder%% Policy%/Preferences permit this, the %%holder|holder%% then requests its %principal’s %%data collector|data-collector%% to initiate a new transaction that will get the %%credential|credential%% from that %%issuer|issuer%%, for which a clean transaction form would then consist of one that contains said %%credential|credential%%. The %%holder|holder%% would then store it in its %principal’s %%wallet|wallet%%, and then proceed to service the %%presentation|presentation%% request as if it had obtained that %%credential|credential%% from its %principal’s %%wallet|wallet%%.
It may happen that the %%wallet|wallet%% does not have such a %%credential|credential%%. However, for every (%%credential|credential%%, %%issuer|issuer%%) pair, the request should specify the URI that is capable of issuing such a %%credential|credential%%. If or when the %%Holder|holder%% Policy%/Preferences permit this, the %%holder|holder%% then requests its %%principal’s|principal%% %%data collector|data-collector%% to initiate a new transaction that will get the %%credential|credential%% from that %%issuer|issuer%%, for which a clean transaction form would then consist of one that contains said %%credential|credential%%. The %%holder|holder%% would then store it in its %%principal’s|principal%% %%wallet|wallet%%, and then proceed to service the %%presentation|presentation%% request as if it had obtained that %%credential|credential%% from its %%principal’s|principal%% %%wallet|wallet%%.
It may also happen that the %%wallet|wallet%% has multiple %%credentials|credential%% that satisfy the request, in which case the %%holder|holder%% must choose the one to use for constructing the %%presentation|presentation%%. Again, the %%Holder|holder%% Policy%/Preferences will specify how this choice needs to be made, and whether or not this can be done automatically by the %%holder|holder%%. If not, the %%holder|holder%% will need to provide for an interaction with a human Colleague that will make such decisions.
......@@ -221,7 +221,7 @@ Typically, and at any point in time, %%parties|party%% are capable of expressing
We will use the term ‘**subject-id (of a %%statement|assertion%% of a %party)**’ to refer to the representation that this %%party|party%% has chosen to use for referring to the subject in said %%statement|assertion%%. A subject-id must have the property of being an %%identifier|identifier%% within every administrative context that this %%party|party%% uses. It need not be humanly interpretable (and preferably is not).
%%parties|party%% need to specify the kinds of %%credentials|credential%% they are willing to issue, the class of %%entities|entity%% (e.g. people, cars, %organizations) for which it will issue them, and the information schema (structure) that it will use in %%credentials|credential%% of such kinds.<sup>[Data Discloser.1]</sup> This allows the %%data discloser|data-discloser%% to construct data objects that conform to this information schema, and present it to the %%issuer|issuer%% component for actual issuing.
%%parties|party%% need to specify the kinds of %%credentials|credential%% they are willing to issue, the class of %%entities|entity%% (e.g. people, cars, %%organizations|organization%%) for which it will issue them, and the information schema (structure) that it will use in %%credentials|credential%% of such kinds.<sup>[Data Discloser.1]</sup> This allows the %%data discloser|data-discloser%% to construct data objects that conform to this information schema, and present it to the %%issuer|issuer%% component for actual issuing.
The %%data discloser policy|data-discloser-policy%% specifies the kinds of (linked-)data-objects that %%credentials|credential%% may be created for. This allows the %%data discloser|data-discloser%% to construct such a (linked-)data-objects for every subject-id that identifies a subject of the class for which a %%credential|credential%% can be issued, which can subsequently be sent to the %%issuer|issuer%% component that can turn it into a %%credential|credential%% of a specific sort.
......@@ -244,7 +244,7 @@ The purpose of the %%issuer|issuer%% component is to issue ‘%credentials’, i
- metadata (e.g. type of %%credential|credential%%, date of issuing and expiration, endpoints, e.g. for revocation checking, %%credential type|credential-type%%, credential advertisements, credential enforcement policy, etc.)
- proofs (e.g. a digital signature by which third %%parties|party%% can prove its provenance and integrity.
Another purpose that an %%issuer|issuer%% might serve is to provide a means that allows any other %%agent|agent%% that somehow has obtained a copy or %%presentation|presentation%% of a %%credential|credential%%, to verify whether or not the data therein is conformant to the business administration of its %%principal|principal%%. We will use the term ‘revocation service’ to refer to such means. Whether or not an %%issuer|issuer%% provides such a service, and what kind of revocation service is provided (e.g. a revocation list, an online revocation status protocol, etc.), is a decision that its %%principal|principal%% should make, and specify in the %%issuer|issuer%% policies%/Preferences.
Another purpose that an %%issuer|issuer%% might serve is to provide a means that allows any other %%agent|agent%% that somehow has obtained a copy or %%presentation|presentation%% of a %%credential|credential%%, to verify whether or not the data therein is conformant to the business administration of its %%principal|principal%%. We will use the term ‘revocation service’ to refer to such means. Whether or not an %%issuer|issuer%% provides such a service, and what kind of revocation service is provided (e.g. a revocation list, an online revocation status protocol, etc.), is a decision that its %%principal|principal%% should make, and specify in the %%issuer policy|issuer-policy%%.
An %%issuer|issuer%% component may issue %%credentials|credential%% in various formats, e.g. as a Verifiable Credential (VC), an Attribute-Based Credential (ABC), an OpenID Connect/JWT token, etc. The issuing %%party|party%% must specify %%credential types|credential-type%% in such a way that if the same %%credential|credential%% is issued in different formats, it is possible for an arbitrary %%verifier|verifier%% to determine whether or not two %%credentials|credential%% that have different formats, are in fact the same. One way of doing this is that the %%issuer|issuer%% generates an %%identifier|identifier%% for every %%credential|credential%% that it constructs (before expressing it in a specific format).
......@@ -263,7 +263,7 @@ After the %%issuer|issuer%% has created a %%credential|credential%% (in one or m
The primary purpose of the %%wallet|wallet%% Component is to (securely) store data, and in particular:
- %%credentials|credential%% - both those that have been issued by the %%issuer|issuer%% (i.e. self-signed %credentials) and those that have been obtained from %%issuers|issuer%% of other %%parties|party%%, and
- %%credentials|credential%% - both those that have been issued by the %%issuer|issuer%% (i.e. self-signed %%credentials|credential%%) and those that have been obtained from %%issuers|issuer%% of other %%parties|party%%, and
- (private) keys e.g. for signing/sealing data on behalf of its %%principal|principal%%.
Other kinds of data may be stored by a %%wallet|wallet%% as well - we will have to see what is practical and makes sense.
......@@ -278,7 +278,7 @@ By ‘securely storing data’ we mean that such data
It is expected that components other than the %%holder|holder%% and %%issuer|issuer%% will (arise and) need access. One example could be a component that is capable of securely signing data on behalf of the %%principal|principal%%. Another example could be a component that implements some kind of credential revocation functionality.
Human beings cannot directly access any %%wallet|wallet%% component, not even the ones they own. They need an %%electronic agent|digital-agent%% that is capable of authenticating them as (an %%agent|agent%% of) the %%party|party%% that owns the %%wallet|wallet%% component, and upon successful authentication provides a User Interface through which the Human Being can instruct this %%electronic agent|digital-agent%% to manage the %wallet’s contents.
Human beings cannot directly access any %%wallet|wallet%% component, not even the ones they own. They need an %%electronic agent|digital-agent%% that is capable of authenticating them as (an %%agent|agent%% of) the %%party|party%% that owns the %%wallet|wallet%% component, and upon successful authentication provides a User Interface through which the Human Being can instruct this %%electronic agent|digital-agent%% to manage the %%wallet’s|wallet%% contents.
In order to make the %%wallet|wallet%% component work, a %%wallet|wallet%% policy%/Preferences object is created by, or on behalf of the %%principal|principal%%, the contents of which remains to be specified.
......@@ -288,9 +288,9 @@ In order to make the %%wallet|wallet%% component work, a %%wallet|wallet%% polic
*The eSSIF-Lab functional architecture is not final. This chapter is an example of how work that is currently being done may already be documented for the purpose of furthering discussions and providing inspiration to readers.*
:::
%%parties|party%% need to deploy (technical) components that act as their %%agents|agent%%. Individuals would typically have a mobile app whose user interface allows them to fulfill any or all of the roles of %%holder|holder%%, %%verifier|verifier%% and %%issuer|issuer%%. Wallet functionality may be included in this app, but it might equally well live in the cloud, as a second %(digital) agent%. An individual might also have (cloud) servers that %%agents|agent%% of other %%parties|party%% may contact for conducting transactions without the need for the individual itself to do something. All of this holds equally well for larger %%organizations|organization%%.
%%parties|party%% need to deploy (technical) components that act as their %%agents|agent%%. Individuals would typically have a mobile app whose user interface allows them to fulfill any or all of the roles of %%holder|holder%%, %%verifier|verifier%% and %%issuer|issuer%%. Wallet functionality may be included in this app, but it might equally well live in the cloud, as a second %%(digital) agent|digital-agent%%. An individual might also have (cloud) servers that %%agents|agent%% of other %%parties|party%% may contact for conducting transactions without the need for the individual itself to do something. All of this holds equally well for larger %%organizations|organization%%.
It is conceivable that the set of SSI functions is spread over multiple %(digital) agents%, in which case there is going to be a need for such %%agents|agent%% to contact one another, and conduct transactions in a way that may differ from doing that with %%agents|agent%% of other %%parties|party%%. Basically, this can be seen as %%colleagues|colleague%% interacting with one another to get things done within one %%organization|organization%%. Seen from the outside, it looks like every %%organization|organization%% has a (smaller or larger) network of %%agents|agent%%. This chapter provides more details on this topic.
It is conceivable that the set of SSI functions is spread over multiple %%(digital) agents|digital-agent%%, in which case there is going to be a need for such %%agents|agent%% to contact one another, and conduct transactions in a way that may differ from doing that with %%agents|agent%% of other %%parties|party%%. Basically, this can be seen as %%colleagues|colleague%% interacting with one another to get things done within one %%organization|organization%%. Seen from the outside, it looks like every %%organization|organization%% has a (smaller or larger) network of %%agents|agent%%. This chapter provides more details on this topic.
The SSI-Agent Network Architecture has two viewpoints:
......@@ -299,13 +299,13 @@ The SSI-Agent Network Architecture has two viewpoints:
An individual %%party|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 agent|digital-agent%%. The set of concerns would include:
- How can electronic components be onboarded as an %%agents|agent%% of this %party?
- How can the integrity of such %%electronic agent|digital-agent%% 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 electronic components be onboarded as an %%agents|agent%% of this %%party|party%%?
- How can the integrity of such %%electronic agent|digital-agent%% 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|credential%%, …)?
- How can the %%party|party%% specify which of its %%agents|agent%% may talk with which other %%agents|agent%%, and for what purposes?
- How should a %%party|party%% specify the policies for the various SSI functionalities - what kind of support would be useful here?
-
%%parties|party%% 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:
%%parties|party%% that want (their %%agents|agent%%) 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|party%% interact with one another at the information level (this includes decentralized semantic interoperability issues, advertising %%credentials|credential%%, how a %%party|party%% can find other %%parties|party%% that issue %%credentials|credential%% that are useful to him, etc.)
- What kinds of underlying technologies must %%agents|agent%% of a %%party|party%% support so as to be(come) interoperable with %%parties|party%% that it wants to interact with?
......@@ -334,7 +334,7 @@ When all is done, %%parties|party%% may issue a (signed) %%statement|assertion%%
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 communication channel|digital-communication-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|credential%% that states the result of the %%transaction|business-transaction%%, i.e. contains the details of the parking permit.
Please note that while %%transactions|business-transaction%% 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|party%% perform are ordered in time, which implies e.g. that the commitment decisions of both %%parties|party%% cannot be done at the same time. Also, in practice, it often happens that a %%party|party%% requires the other %%party|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.
Please note that while %%transactions|business-transaction%% 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|party%% perform are ordered in time, which implies e.g. that the commitment decisions of both %%parties|party%% cannot be done at the same time. Also, in practice, it often happens that a %%party|party%% requires the other %%party|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|credential%% will need to support such ‘asynchronous’ ways of working.
### 5.2. Transaction Negotiation Phase
......@@ -347,7 +347,7 @@ This phase starts by the requester sending a transaction request to the provider
*Figure 4: High-level transaction negotiation.*
This 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 %%communication channel|communication-channel%%, i.e. a secure %%communication channel|communication-channel%% through which provider and requester can both request and obtain (%presentations of) %%credentials|credential%%, 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.
This 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 %%communication channel|communication-channel%%, i.e. a secure %%communication channel|communication-channel%% through which provider and requester can both request and obtain (%%presentations|presentation%% of) %%credentials|credential%%, 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 %%presentations|presentation%% and responding to such requests may very well consist of multiple requests and associated responses.
......@@ -359,7 +359,7 @@ Conversely, the citizen might request the (alleged) municipality to provide %%cr
### 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|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|credential%% has been changed/tampered with since it was issued). From this, it follows that any %%party|party%% can issue any kind of %%credential|credential%% for any %%entity|entity%% that it knows to exist. A %%credential|credential%% does not need to be about a person or an %%organization|organization%%, but it can also refer to an order, a delivery, a seat-reservation, a prescription, etc.
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|party%% has issued with proof of provenance (i.e. anyone else can determine the identity of that %%issuer|issuer%%) and a proof of integrity (i.e. anyone can determine whether or not the content of the %%credential|credential%% has been changed/tampered with since it was issued). From this, it follows that any %%party|party%% can issue any kind of %%credential|credential%% for any %%entity|entity%% that it knows to exist. A %%credential|credential%% does not need to be about a person or an %%organization|organization%%, but it can also refer to an order, a delivery, a seat-reservation, a prescription, etc.
We foresee two ways in which %%credentials|credential%% can be issued:
......
......@@ -17,6 +17,7 @@
beg = "(?<=\W%%)"
mid = "(?<=\|)"
end = "(?=%%\W)"
ss = "(?:['’]?s)?"
dutyright = "(?:dut(?:y|ies)|rights?)"
dutyright = "%{dutyright}(?:-*(?:/|and|or|and/or)-*%{dutyright})?"
......@@ -29,7 +30,7 @@ dutyrighttype = "%{dutyright}-types?"
// `filter "*.txt"` - any .txt file in the root folder
// `filter "**/*.txt"` - any .txt file
filter "docs/terms/credential-type.md"
filter "docs/functional-architecture.md"
// PREPROCESSING: convert single-%-notations into %%-notations.
......@@ -38,11 +39,16 @@ filter "docs/terms/credential-type.md"
// with "$1$2$3"
// First, convert %show text% into %%show text%%
replace-regex "(?<=\s%)(([\w/-]|'|\s)*)(?=%([,.]?\s|-\w))"
// Test set: none may match: %verif%er, %verif"ier%, "%verifier%", `%verifier%`
// Test set: all must match: %my verifier%, (%verifiers%), %verifier's%, %verifier’s%, (%(ver)/ifier%):., %(our) (vfyr)%, %verifier's%. %verifier’s%.....
// replace-regex "(?<=\s\(?%)(\w|\s|\(|\)|[/-’'"])+(?=%([)":,.!?]*\s|-\w))"
replace-regex "(?<=\s\(?%)([^%]+)(?=%(([):,.!?]|\[[^\]]*\]){0,2}\s|-\w))"
with "%$1%"
// Only thereafter can we convert %showtext (words without trailing `%`-char) into %%showtext%%
replace-regex "(?<=\s%)(([\w/-]|')*)(?=[,.]?\s)"
// Test set: none may match: %verif%er, %(our) (verifier)%,
// Test set: all must match: %verifier non-matching-text, %verifiers, %verifier's, %verifier’s, %verifier:, (%verifiers), %verifier's..... %verifier’s,?.!?
replace-regex "(?<=(?:\s\(?|/)%)((\w+((/|-|’|')\w)?)+)(?=(\)?[:,.!?]*\s))"
with "%$1%%"
// Then, we can expand %%show text%% into %%show text|show text%%
......@@ -68,25 +74,25 @@ with "$1-$2"
// ACTUAL PROCESSING: now we need to convert well-known `lowercase-show-text`s to appropriate `reftexts`
// [A]
replace-regex "%{mid}(action|actor|agent|assertion|author)'?s%{end}"
replace-regex "%{mid}(action|actor|agent|assertion|author)%{ss}%{end}"
with "$1"
// [B]
replace-regex "%{mid}(business-transaction)'?s?%{end}"
replace-regex "%{mid}(business-transaction)%{ss}?%{end}"
with "$1"
// [C]
// for 'claim', see 'statement'
replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)'?s?%{end}"
replace-regex "%{mid}(colleague|concept|credential(-type)?|commitment-decision)%{ss}?%{end}"
with "$1"
replace-regex "%{mid}communications?-(channel|session)'?s?%{end}"
replace-regex "%{mid}communications?-(channel|session)%{ss}?%{end}"
with "communication-$1"
// [D]
replace-regex "%{mid}(definition|dependent|dictionary-file|dictionary|documentation-interop)'?s?%{end}"
replace-regex "%{mid}(definition|dependent|dictionary-file|dictionary|documentation-interop)%{ss}?%{end}"
with "$1"
replace-regex "%{mid}(?:electronic-|digital-)(actor|agent|colleague|communication-channel|policy)'?s%{end}"
replace-regex "%{mid}\(?(?:electronic|digital)\)?-(actor|agent|colleague|communication-channel|policy)%{ss}%{end}"
with "digital-$1"
replace-regex "%{mid}(%{dutyrighttype}|%{dutyright})%{end}"
......@@ -94,17 +100,17 @@ with "pattern-duties-and-rights"
replace-regex "%{mid}data-(collector|discloser)-polic(y's|ies)%{end}"
with "data-$1-policy"
replace-regex "%{mid}data-(collector|discloser)'?s?%{end}"
replace-regex "%{mid}data-(collector|discloser)%{ss}?%{end}"
with "data-$1"
// [E]
replace-regex "%{mid}(employee|employer)'?s%{end}"
replace-regex "%{mid}(employee|employer)%{ss}%{end}"
with "$1"
replace-regex "%{mid}(legal-)?entit(y's|ies)%{end}"
with "$1entity"
// [G]
replace-regex "%{mid}(glossary-file|guardian(ship)?(-relationship)?(-type)?)'?s%{end}"
replace-regex "%{mid}(glossary-file|guardian(ship)?(-relationship)?(-type)?)%{ss}%{end}"
with "$1"
replace-regex "%{mid}glossar(y's|ies)%{end}"
with "glossary"
......@@ -117,20 +123,20 @@ with "governance"
// [H-I-J-K] (all holder, issuer, verifier and wallet stuff, too)
// for associated policies, see [P]
replace-regex "%{mid}(holder|issuer|verifier|wallet|identifier|jurisdiction(-governor)?|knowledge(-governor)?)'?s%{end}"
replace-regex "%{mid}(holder|issuer|verifier|wallet|identifier|jurisdiction(-governor)?|knowledge(-governor)?)%{ss}%{end}"
with "$1"
// [L-M]
replace-regex "%{mid}(legal-jurisdiction|legal-system|mental-model)'?s%{end}"
replace-regex "%{mid}(legal-jurisdiction|legal-system|mental-model)%{ss}%{end}"
with "$1"
// for 'legal entities', see 'entities'
// [O]
replace-regex "%{mid}(objective|organization|owned|owner|ownership)'?s%{end}"
replace-regex "%{mid}(objective|organization|owned|owner|ownership)%{ss}%{end}"
with "$1"
// [P]
replace-regex "%{mid}(participant|pattern-file|pattern|(peer-)(actor|agent)|policy-governor|presentation-request|presentation|principal)'?s%{end}"
replace-regex "%{mid}(participant|pattern-file|pattern|(peer-)(actor|agent)|policy-governor|presentation-request|presentation|principal)%{ss}%{end}"
with "$1"
replace-regex "%{mid}(|peer-)part(y's|ies)%{end}"
with "$1party"
......@@ -139,21 +145,21 @@ with "$1policy"
// [R-S]
// For 'rights', see [D]uties
replace-regex "%{mid}(risk|scope-file|scope|ssi-agent)'?s%{end}"
replace-regex "%{mid}(risk|scope-file|scope|ssi-agent)%{ss}%{end}"
with "$1"
replace-regex "%{mid}(statement|claim)'?s%{end}"
replace-regex "%{mid}(statement|claim)%{ss}%{end}"
with "assertion"
// [T]
// for transaction data collector/discloers policies, see [P]
replace-regex "%{mid}(term-file|term|transaction-(agreement|data-(collector|discloser)|form|proposal))'?s%{end}"
replace-regex "%{mid}(term-file|term|transaction-(agreement|data-(collector|discloser)|form|proposal))%{ss}%{end}"
with "$1"
replace-regex "%{mid}transaction'?s?%{end}"
replace-regex "%{mid}transaction%{ss}?%{end}"
with "business-transaction"
// [V]
// for verifier stuff - see holder
replace-regex "%{mid}(verifiable-credential|verifier)'?s%{end}"
replace-regex "%{mid}(verifiable-credential|verifier)%{ss}%{end}"
with "$1"
replace-regex "%{mid}vocabular(y's|ies)%{end}"
with "vocabulary"
......
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