># Gaia-X Notarisation API Roles, Trust Domains & Reference Use Cases

**Version:** 0.10

**Date:** 18 February 2022

**Editors:**
* [Carsten Stöcker](mailto:[e-mail]), [Spherity GmbH](https://spherity.com/)
* [Ricky Thiermann](mailto:[e-mail]), [Spherity GmbH](https://spherity.com/)

## 1 Notarisation API Purpose

The purpose of the notarisation API service is to attest master as well as transaction data and transform them to W3C compliant Verifiable Credentials (VC).

These VCs are tamper-proof digital assertions about certain attributes of an identity subject that can be used to establish trust in a given use case domain.

VCs can be assertions about humans, organisations, objects, machines, algorithms, places, living species, or data assets. VCs can be either assertions about myself (self-issued VC) or assertions about another entity [1], [2], [3].

## 2 Generic Notarisation API Roles

The notarisation process involves the following roles:

| ID | Notarisation Role | Description | Credentialing Activities |
| -------- | -------- | -------- | -------- |
| R.1 | Super Notary | Is a well-known entity that is acting as the root of trust. A super notary creates a root issuing credential as self-asserted VC and with an eIDAS signature. | Issues a notary authorization credential to any authorized notary. |
| R.2 | Business owner | Authorized person or entity that wants an assertion to be notarised | Initiates a notarisation request |
| R.3 | Notarisation Operator | Responsible employee of the notarisation office that verifies assertions | Verifies data and triggers the issuance of VCs to a given DID |
| R.4 | Notarisation Entity (Issuer) | Accountable natural person or legal entity that oversees the notarisation service | Issues notarised assertions in from of a verifiable credential with the help of the notarisation system that is under its control |
| R.5 | Holder | Entity possessing one or more notarised assertions | Acquires, stores, and presents notarised assertions in form of verifiable credentials |
| R.6 | Subject | Entity about which assertions are notarised | In many cases the holder of a verifiable credential is the subject, but in many other cases it is not |
| R.7 | Administrator | Responsible employee of the notarisation service performing system administration activities | Sets up the system and maintains operator identities |

It shall be understood that the Business Owner and Notarisation Operator role can be automated to avoid manual intervention in high throughput notarisation scenarios. Automation of such processes requires validation of the automation logic and system as well as process controls to ensure that notarised assertions are issued in accordance with use case specific policies and regulations. The Notarisation Entity is accountable for all notarisation system and process controls.

It shall be further understood that in certain use cases business owner, holder and subject can be the same entity. To reduce optionality and complexity of our Notarisation API reference implementation, we make the following assumptions.

| ID | Assumption | Description |
| -------- | -------- | -------- |
| A.1.1 | Holder DID | There is a business process in place that provides the DID of the holder to the business operator. Implementation of such a business process is use case dependent and therefore out of scope of the Notarisation API reference implementation. |
| A.1.2 | Holder & Subject | Reference implementation will focus on use cases in which holder and subject are one and the same entity represented by a DID. |
| A.1.3 | Holder & Subject Identifier | There is a business process in place that provides the subject identifier to the business operator. Implementation of such a business process is use case dependent and therefore out of scope of the Notarisation API reference implementation. We assume that the Subject Identifier is the Holder DID. |
| A.1.4 | Subject Assertion Verification | This process is use case dependent, part of a use case specific business processes and deemed out of scope for the reference implementation. |

It shall be understood that a holder can be authorized by the notary to issuer further credentials. In this case the holder would need a holder wallet such as the organisational credential mananager (OCM) or a personal credential manager (PCM) which is integrated with the Notarisation API modules so that the holder can also act as an authorized notary. In oder to reduce complexity the reference implementation will provide ACA-Py agents that can provide bother features, Notarisation API and very basic PCM/OCM capabilities. Examples are AISBL membership and principal credentials which are outlined as a more detailed reference use case below.

**To be clarified:** There can be a further simplification if business owner and holder are one and the same entity as well. I am personally not in favour of this simplification, as I think the business owner role is a key role as defined in the SRS and we would use some functional features / APIs if we would combine both roles.

## 3 Notarisation API Trust Domains & Use Case Examples

Any verifiable credential must be issued within a trust domain that is accepted within a given use case domain. Such a trust domain is typically hierarchically governed under a well-known root of trust. If a trust domain of a notary is unknown the notary itself is unknown and cannot be trusted.

Examples for trust domains are:

| ID | Trust Domain | Notarisation Entity | Super Notary (aka Root of Trust) |
| -------- | -------- | -------- | -------- |
| TD.1 | Legal Notarisation Service | Notary | Chamber of Notaries |
| **TD.2** | **Organisational Membership** | **Membership Department** | **Global Headquarter** |
| TD.3 | Legal Entity Identifier (vLEI) | vLEI Issuer | GLEIF |
| TD.4 | Supply Chain Identifier | GS1 Country | GS1 Global |
| TD.5 | Vaccination Certificate | Doctor Office | Government Agency for Disease control and prevention |
| TD.6 | Government Credentials | Local Government | Federal Government |
| TD.7 | Driving License | Driving licence office | Department of Transport |
| TD.8 | Car TÜV Certificate | Local TÜV Office | Global TÜV Organisation |
| TD.9 | Product Passport | OEM Department | OEM Headquarter |

It shall be understood that a "Super Notary" entity governs a trust domain. Therefore, the entity identifier must be verifiable and well-known. The notarisation API establishes a verifiable root of trust for the super notary entity by using eIDs and mechanisms developed in the EBSI eIDAS bridge project.

In a each trust domain a Super Notary issues authorization credentials to a Notarisation Entity so that a holder or verifier can check whether Notarisation Entity was authorized by a well-known Super Notary. It shall be further understood that a super notary can be part of another overlay trust domain in which verifiable assertions are made about the super notary. These more complex trust framework concepts are deemed out of scope.

To reduce optionality and complexity of our Notarisation API reference implementation, we make the following assumptions.

| ID | Assumption | Description |
| -------- | -------- | -------- |
| A.2.1 | Well-known Super Notary | The Super Notary is well-known by default. The reference implementation will not establish well-known instruments to ensure that the super notary is well-known among all stakeholders of a given use case domain |
| A.2.2 | Authorization Chains | Multi-step authorization chains, aka trust chains, can be involved in real world use cases. We restrict our reference implementation to a two- or three-step scenario consisting of a super notary and a notary |
| A.2.3 | Trust Domains | In real world implementations multiple trust domains can be involved. To reduce complexity in selecting and managing multiple trust domains and authorisation credentials we restrict the reference implementation to one trust domain. The reference framework is extensible to support multiple trust domains at a later stage.|
| A.2.4 | Trusted Notary (Issuer) | A business owner or holder will only exchange data with a trusted Notarisation Service. Therefore, a business owner or holder might want to check the authorization credential within a given trust domain prior to exchanging data with the service. Such will be part of the business logic of a give use case and therefore deemed out of scope for the reference implementation. |
| A.2.5 | eID Integration | eID integration is primarily relevant for the super notary. To enable holders and verifiers to authenticate the entity that is serving as a root of trust, the eID of the super notary is used to co-sign a super notary root crdential or an authorization credential for a notarisation entity.|

## 4 Reference Use Case Example: Membership Credentials

To have a simple to understand use case that is relevant for the Gaia-X trust framework, we focus our reference implementation concept example on **General Membership Credentials** and the Membership Trust Domain (TD.2). This use case demonstrates
* organisation acting as trust anchor (e.g. Gaia-X AISBL)
* organisational members (e.g. GAIA-X participants with associated master data)
* business owner requesting a credential issuance process (e.g. Gaia-X membership department)
* transformation of membership certificates to VCs (e.g. Gaia-X membership credentials)

Such a reference implementation can be described by the following requirements:

| ID | Category | Description | Activities |
| -------- | -------- | -------- | -------- |
| ER.1 | Super Notary (root of trust) | Global Headquarter | notarises authorisation credentials for the local membership department |
| ER.2 | Notarisation Entity | Local Membership Department | notarises and issues membership credentials |
| ER.3 | Notarisation Operator | Employees of Membership Approval Team (to be configured in the IAM) | check membership requests and trigger the issuance of membership VCs |
| ER.4 | Business Owner | Membership acquisition team | Identifies new members and requests their enrolment |
| ER.5 | Holder | New Member Entity | Requests new membership credential |

Concrete examples for membership credentials are:
* Gym membership credentials
* Employee employment, authorization, qualification or role credentials
* University student credentials
* AISBL membership credentials

## 5 Reference Use Case Example: Membership Notarisation Events

In this paragraph we decribe notarisation events when new credentials are created in the membership use case scope.

In a most simple set-up with focus on a simple 'Holder Membership Assignment' for a natural person (gym membership) or a legal entity (AISBL member organisation) there two notarisation event types (NE.1 to NE.3).

In a more advanced enterprise use case legal entity and human principals that are acting on behalf of the member organsiation are required. Here we need to differentiate between five notarisation event types (NE.1 to NE.5):

| ID | Notarisation Event | Entity Type | Exmaple | Verifiable Credential Type |
| -------- | -------- | -------- | ------ | ------ |
| NE.1 | Super Notary Root Instantiation | Legal Entity | AISBL Headquarter | Root issuing credential as self-asserted VC with eIDAS signature |
| NE.2 | Notarisation Entity Authorization | Legal Entity | AISBL Membership Deptartment | Authorization credential of the notarisation entity signed with eID and DID of the super notary. |
| NE.3 | Holder Membership Assignment | Legal Entity | Member Organisation | Membership Credential signed with the DID of the notary and chained with the respective authorization credential. |
| NE.4 | Holder Principal Authorisation | Legal Entity | Member Organisation | Authorization credential for assigning a principle that can act on behalf of the membership organisation signed with the DID of the notary and chained with the respective notary authorization credential. |
| NE.5 | Holder Membership Principal Assignment | Human | Principal | Authorization of a principle that can act on behalf of the membership organisation signed with the DID of the notary and chained with the respective principal authorization credential. |

It shall be understood that super notary and notarisation entity could be the same entity in a simpler reference set-up.

It shall be further understood that there can be multiple membership credentials representing different membership types. In case of AISBL membership credentials there are four membership types. Credential schemas might be different for different member types.
* Association
* Small Enterprise
* Medium Enterprise
* Large Enterprise

The reference implementation will provide instruments to select the respective membership type credential schemas in the notarisation request processing module.

## 6 Details on AISBL Membership Contept: Credential Set-up, Process & Infrastructure

The membership credentials can be applied to AISBL memberships. This use case is depicted in the following picture.

*Figure 1: AISBL Membership Credential Set-up*

We suggest to establish a five step credential issuance and acquisition process as outline in the process flow in the picture below:

*Figure 2: AISBL Membership Credentialing Process*

The implementation of this use cases requires the follwing agent tenats (e.g. a multi-tenancy set-up for all AISBL agents) or instances:
1. Headquarter ACA-Py
2. Marketing Department ACA-Py
3. Member Organisation ACA-Py
4. Principal ACA-Py (optional)

*Figure 3: AISBL Membership Credentialing Process & Agent Infrastructure*

## 7 Credential Chaining and the eIDAS Bridge

Authorisation credentials are used to establish *delegated authorities* of entities that are acting in accordance to policies, rules and assigned roles of a membership framework.

The chaining of authorization credentials establishes a *trust chain* that can be verified up to the *root of trust* of the membership framework which is the AISBL headquarter in our case.

The *eIDAS Bridge* was developed by the European Commission to establish a legal compliant link between SSI based on
DIDs/VCs and existing digital identities based on X.509. The eIDAS Bridge implies that verifiable credentials are signed with an additional (qualified) electronic signature or seal of the issuer from a qualified trust service provider. Existing eIDAS validation mechanisms can be used to make the authenticity and integrity of the VC evident against 3rd parties.

To increase the trust in the membership credential system further we propose the use of *root issuing credentials* for the AISBL headquarter. The AISBL root issuing credentials is signed with both, the DID and the eID. This approach extends the credential based trust chain to the root of trust or the *EU Trusted List of QES Providers*. By performing a standard X.509 signature / seal verification a verifier of the membership credential can be legally prove authenticity of AISBL headquarter entity.

According to the reference model described in this document a membership principal assignment credential is issued by the member organisation. Every membership principal assignment credential is chained to a principal authorisation credential which was issued by the AISBL membership department to a membership organisation. The principal authorisation credential is chained to membership department authorisation credential which is then chained to the super notary root issuing credential of the AISBL headquarter, which is also signed with its X.509 certificate.

When credentials are chained together a verifier can check the entire trust chain up to AISBL headquarter and the EU Trusted List of QES Providers.

The verification process shall verify the entire credential chain:
*Figure 4: Credential chaining for membership principal assignment credential*

## 8 Use of AISBL Principal Membership as Authentication Credentials for the Gaia-X Portal

After principals of a membership organisation received their membership credentials they might want to present their credential to an external service such as the Gaia-X portal. The authentication & authorisation module of the portal shall perform a three step verification process:
1. Verification of the membership principal assignment credential
2. Verification of the credential chain up to the super notary root
3. Verification of the super notary root credential with eIDAS bridge Verify API

*Figure 5: Required steps to verify AISBL membership credentials in the authentication & authorization module of the Gaia-X Portal*

## 9 AISBL policy and federator role specifications

The follwoing context information shall be noted:
* There are AISBL membership policy documents. We have not yet found and reviewed these documents to align this document with the more specific AISBL policy specifications.
* The federator role is not yet reflected the digures depicted above. Adding this role into the hierarchy of authorization steps is straight forward.

Requirenments for the AISBL policy and federator specifications shall be defined together with [e-mail].

## References

[1] [Gaia-X Notarisation Federated Services Specifications](https://www.gxfs.eu/specifications/)
[2] [Gaia-X Notarisation API Homepage](https://www.gxfs.eu/notarization-api/)
[3] [Gaia-X Notarisation API Software Requirements Specifications](https://www.gxfs.eu/download/1725/)