Skip to content

Commit 0663982

Browse files
jason-foxjason-fox
committed
Update Readme
1 parent b275ede commit 0663982

File tree

1 file changed

+132
-2
lines changed

1 file changed

+132
-2
lines changed

‎README.md‎

Lines changed: 132 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,16 +45,146 @@ commands used to generate credentials using a REST API
4545
> ― Remarks on Signing the Intermediate-Range Nuclear Forces Treaty
4646
4747

48-
## What are Verifiable Credentials
48+
## What are Verifiable Credentials?
49+
50+
Verifiable credentials are the digital equivalent of something like a membership card or a drivers
51+
license. They are a representation of some sort of ownership or rights that a user claims to hold.
52+
Verifiable credentials follow an international W3C standard and are cryptographically secure, so they
53+
can be checked much like in the real world.
54+
55+
The idea behind verifiable credentials is that they can be issued and verfied by anyone - that is that there is no centralised owner of all of the information. This contrasts with the standard OAuth2
56+
Authorization Code Grant flow which relies on a user logging in somewhere to prove who they are.
57+
58+
For example in the physical world, when a tourist enters new a country, they typcially need to pass through border control, where they are asked to provide a valid identity document or passport. The border guard needs to check both that the passport is real, and that the passport actually belongs to the tourist himself. Other requirements may also need to be met, maybe a specific visa or vaccination certificate is required.
59+
60+
Now, the tourist's passport has been provided by their own national government, so the border guard,
61+
as well as checking that the photo matches the recipient, is implicitly checking that a document provided by a third party is real, without necessarily directly contacting the country concerned.
62+
63+
With Verifiable credentials, a check for the validity of the document can be made based on the some sort of agreed cryptographic proof, the decoded document holds the claimed rights and also connects directly to both the subject of the credential (similar to the passport photograph) and the identity of the issuer (similar to the origin country of origin the passport itself). In both cases this identity needs to resolve to a unique id, where the id has been pre-generated by the owner.
64+
65+
66+
## What are Decentralised Identifiers?
67+
68+
[Decentralised Identifiers](https://www.w3.org/TR/did-1.0/) are a mechanism to create verifiable, persistent identifiers without the need to defer to a central authority. A digital identifier consists of a URN made up of several sections,
69+
each separated by a colon. They start with the namespace `did` , followed by a decentralised identifier method (such as `web` or `ethr`, `key`). The method defines how the rest of the identifier can be decoded and resolved. For example the term [`did:web`](https://w3c-ccg.github.io/did-method-web/) refers to a method for creating decentralized identifiers that are hosted on a publicly accessible web domain, `did:ethr` is used by [Etherium-based identities](https://github.com/uport-project/ethr-did-registry) and a [`did:key`](https://w3c-ccg.github.io/did-key-spec/) holds an encoded public key. the remaining sections of the URN will resolve to allow a verifier to check if the identity has been used correctly.
70+
71+
For example `did:web:fiware.github.io:tutorials.Step-by-Step:alice` is referring to a document found at
72+
[`https://fiware.github.io/tutorials.Step-by-Step/alice/did.json`]
73+
74+
```json
75+
{
76+
"@context": [
77+
"https://www.w3.org/ns/did/v1",
78+
"https://w3id.org/security/suites/jws-2020/v1"
79+
],
80+
"id": "did:web:fiware.github.io:tutorials.Step-by-Step:alice",
81+
"verificationMethod": [
82+
{
83+
"id": "did:fiware.github.io:tutorials.Step-by-Step:alice#owner",
84+
"type": "JsonWebKey2020",
85+
"controller": "did:web:fiware.github.io:tutorials.Step-by-Step:alice",
86+
"publicKeyJwk": {
87+
"kty": "EC",
88+
"crv": "secp256k1",
89+
"x": "Nd3DeQ7G/1pTeYM6viWK6plbSD9E7cA9C2ONG9qG3CQ=",
90+
"y": "LuMt0dFWni1/fs/VqfjNOHAZT3PWGxKU8kUlLffGtjM="
91+
}
92+
}
93+
],
94+
"authentication": [
95+
"did:web:fiware.github.io:tutorials.Step-by-Step:alice#owner"
96+
],
97+
"assertionMethod": [
98+
"did:web:fiware.github.io:tutorials.Step-by-Step:alice#owner"
99+
]
100+
}
101+
```
49102

50-
## What are Distributed Identifiers
51103

104+
Which in turn is a JSON-LD document which holds a list of verification methods which can be used to valid the `id`. In this case `JsonWebKey2020` refers to a [JSON Web Signature](https://w3c-ccg.github.io/lds-jws2020/)
52105

53106
# Architecture
54107

108+
For the purpose of this tutorial, we will take the demo Farm Management Information System (FMIS)
109+
from the previous tutorial, and alter access to the vet's context broker. Remember that within our
110+
data space we effectively have three context brokers owned by the Farmer, a Vet and a Contract labourer
111+
respectively.
112+
113+
- The default tenant which holds **Building** data and is used for collating data from all systems
114+
- The `farmer` tenant which holds **Animal**, **Device** and **AgriParcel** information
115+
- The `contractor` tenant holds **Animal** data about animals needing additional care.
116+
- The `vet` tenant which holds **Animal** data about new-born animals
117+
118+
119+
Within the data space, the **Vet** wishes to restrict access to her data to legitmate users only:
120+
121+
- Those who have bought access to her data, who are accredited users of **Vets Mart*
122+
- Animal welfare officers who are legally alloweed access who are accredited by the national **Government**
123+
124+
This tutorial will not complete the enforcement of access rules, but will show how accredited users would be
125+
able to demonstrate that they are legitimately from those organisations.
126+
127+
128+
129+
Therefore the overall architecture will consist of the following elements:
130+
131+
- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will send and receive requests
132+
using
133+
[NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/raw/master/spec/updated/generated/full_api.json).
134+
This is split into the following systems, each running on their own tenant:
135+
- The default tenant
136+
- The `farmer` tenant
137+
- The `contractor` tenant
138+
- The `vet` tenant
139+
- The FIWARE [IoT Agent for UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/) which will receive
140+
southbound requests using
141+
[NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/raw/master/spec/updated/generated/full_api.json)
142+
and convert them to
143+
[UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)
144+
commands for the devices
145+
- The underlying [MongoDB](https://www.mongodb.com/) database :
146+
- Used by the **Orion Context Broker** to hold context data information such as data entities, subscriptions and
147+
registrations
148+
- Used by the **IoT Agent** to hold device information such as device URLs and Keys
149+
- An HTTP **Web-Server** which offers static `@context` files defining the context entities within the system.
150+
- The **Tutorial Application** does the following:
151+
- Acts as set of dummy [agricultural IoT devices](https://github.com/FIWARE/tutorials.IoT-Sensors/tree/NGSI-LD)
152+
using the
153+
[UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)
154+
protocol running over HTTP.
155+
- Displays a running Farm Management Information System (FMIS)
156+
157+
In additionl, our **Vet** will be using a dummy data space connector, it includes:
158+
159+
- A FIWARE [Credentials Configuration Service](https://github.com/FIWARE/credentials-config-service) to hold the location of services it should trust
160+
- A FIWARE [trusted-issuers-list]https://github.com/FIWARE/trusted-issuers-list/) which returns the list of trusted roles for each issuer's credentials
161+
162+
Since all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run
163+
from exposed ports.
55164

56165
# Start Up
57166

167+
All services can be initialised from the command-line by running the
168+
[services](https://github.com/FIWARE/tutorials.Verifiable-Credentials/blob/NGSI-LD/services) Bash script provided within the
169+
repository. Please clone the repository and create the necessary images by running the commands as shown:
170+
171+
```console
172+
git clone https://github.com/FIWARE/tutorials.Verifiable-Credentials.git
173+
cd tutorials.Linked-Data
174+
git checkout NGSI-LD
175+
176+
./services orion|scorpio|stellio
177+
```
178+
179+
> [!NOTE]
180+
>
181+
> If you want to clean up and start over again you can do so with the following command:
182+
>
183+
> ```
184+
> ./services stop
185+
> ```
186+
187+
58188
59189
# Verifiable Credentials
60190

0 commit comments

Comments
 (0)