From da2f4b1f47d86c798a3e965afa0d8a61f89985b7 Mon Sep 17 00:00:00 2001 From: Jan Christoph Ebersbach Date: Thu, 30 May 2024 09:34:52 +0200 Subject: [PATCH] docs: add component diagram that shows the process for updating a DID document --- docs/figures/architecture.puml | 10 +++--- docs/figures/did-creation-components.puml | 33 +++++++++++++++++++ .../figures/did-creation-components.svg | 1 + .../public/figures/did-web-server-context.svg | 2 +- docs/src/content/docs/getting-started.md | 14 ++++++++ docs/src/content/docs/index.md | 9 ++--- 6 files changed, 59 insertions(+), 10 deletions(-) create mode 100644 docs/figures/did-creation-components.puml create mode 100644 docs/public/figures/did-creation-components.svg diff --git a/docs/figures/architecture.puml b/docs/figures/architecture.puml index a83a20e..d0bf45d 100644 --- a/docs/figures/architecture.puml +++ b/docs/figures/architecture.puml @@ -1,7 +1,7 @@ @startuml ../public/figures/did-web-server-context !include ./styles/styles.puml -title "Context diagram of did-web-server" +title "System Context Diagram of did-web-server" !include ./styles/c4/C4_Context.puml !include ./styles/sprites/icons/font-awesome-6/magnifying_glass.puml @@ -14,14 +14,14 @@ title "Context diagram of did-web-server" Person(admin, "Administrator", "Owner of server instance", $sprite="user_gear") Person(person, "Person", "Controller of DID identifier", $sprite="user") System_Ext(wallet, "Wallet", "Store of controlling keys for DID identifier", $sprite="wallet") -System(system, "did-web-server", "Self-sovereign did:web identifier store", $sprite="server") +System(server, "did-web-server", "Self-sovereign did:web identifier store", $sprite="server") System_Ext(resolver, "DID Resolver", "did:web compatible DID resolver", $sprite="magnifying_glass") Rel(person, wallet, "manages", "") -Rel(wallet, system, "updates DID Document", "") +Rel(wallet, server, "updates DID Document", "") Rel(person, admin, "submits request for did:web identifier", "") -Rel(admin, system, "creates and deactivates DIDs", "") -Rel(resolver, system, "resolves DIDs", "") +Rel(admin, server, "creates and deactivates DIDs", "HTTPS") +Rel(resolver, server, "resolves DIDs", "HTTPS") SHOW_LEGEND() @enduml diff --git a/docs/figures/did-creation-components.puml b/docs/figures/did-creation-components.puml new file mode 100644 index 0000000..e98e368 --- /dev/null +++ b/docs/figures/did-creation-components.puml @@ -0,0 +1,33 @@ +@startuml ../public/figures/did-creation-components +!include ./styles/styles.puml + +title "Component diagram for creating and updating a DID document" + +!include ./styles/c4/C4_Context.puml +!include ./styles/c4/C4_Component.puml +!include ./styles/sprites/icons/font-awesome-6/magnifying_glass.puml +!include ./styles/sprites/icons/font-awesome-6/server.puml +!include ./styles/sprites/icons/font-awesome-6/key.puml +!include ./styles/sprites/icons/font-awesome-6/user_gear.puml +!include ./styles/sprites/icons/font-awesome-6/building.puml +!include ./styles/sprites/icons/font-awesome-6/file.puml +!include ./styles/sprites/icons/font-awesome-6/file_contract.puml +!include ./styles/sprites/icons/font-awesome-6/wallet.puml + +System_Ext(wallet, "Wallet", "Store of controlling keys for DID identifier", $sprite="wallet") +System(server, "did-web-server", "Self-sovereign did:web identifier store", $sprite="server") +Component_Ext(key, "Cryptographic Key", "", $sprite="key") +Component(diddoc, "DID Document", "", $sprite="file") +Component(vc, "Verifiable Credential", "", $sprite="file_contract") +Component(vp, "Verifiable Presentation", "", $sprite="file_contract") + +Rel(wallet, key, "stores", "") +Rel_L(vp, vc, "includes", "") +Rel_L(vc, diddoc, "includes", "") +Rel(key, vc, "signs", "") +Rel(key, vp, "signs", "") +Rel_D(vp, server, "submitted to", "HTTPS") +Rel_U(server, diddoc, "stores", "") + +SHOW_LEGEND() +@enduml diff --git a/docs/public/figures/did-creation-components.svg b/docs/public/figures/did-creation-components.svg new file mode 100644 index 0000000..b12a900 --- /dev/null +++ b/docs/public/figures/did-creation-components.svg @@ -0,0 +1 @@ +Component diagram for creating and updating a DID documentWallet Store of controlling keys forDID identifierdid-web-server Self-sovereign did:webidentifier storeCryptographic KeyDID DocumentVerifiable CredentialVerifiablePresentationstoresincludesincludessignssignssubmitted to[HTTPS]storesLegend ▯ system ▯ component ▯ external_system ▯ external_component  \ No newline at end of file diff --git a/docs/public/figures/did-web-server-context.svg b/docs/public/figures/did-web-server-context.svg index 19d1a2d..7ac7791 100644 --- a/docs/public/figures/did-web-server-context.svg +++ b/docs/public/figures/did-web-server-context.svg @@ -1 +1 @@ -Context diagram of did-web-serverAdministrator Owner of server instancePerson Controller of DID identifierWallet Store of controlling keys forDID identifierdid-web-server Self-sovereign did:webidentifier storeDID Resolver did:web compatible DIDresolvermanagesupdates DIDDocumentsubmits request fordid:web identifiercreates anddeactivates DIDsresolves DIDsLegend ▯ person ▯ system ▯ external_system  \ No newline at end of file +System Context Diagram of did-web-serverAdministrator Owner of server instancePerson Controller of DID identifierWallet Store of controlling keys forDID identifierdid-web-server Self-sovereign did:webidentifier storeDID Resolver did:web compatible DIDresolvermanagesupdates DIDDocumentsubmits request fordid:web identifiercreates anddeactivates DIDs[HTTPS]resolves DIDs[HTTPS]Legend ▯ person ▯ system ▯ external_system  \ No newline at end of file diff --git a/docs/src/content/docs/getting-started.md b/docs/src/content/docs/getting-started.md index 4b06459..6522799 100644 --- a/docs/src/content/docs/getting-started.md +++ b/docs/src/content/docs/getting-started.md @@ -62,6 +62,20 @@ docker run -it --rm -p 3000 --env-file .env -u "$(id -u):$(id -g)" -v "$PWD:/run Congratulations, the server is up and running! It does not contain any DID, yet. Let's create the first DID: `did:web:localhost%3A3000:person1` +did-web-server is using DIDs, Verifiable Credentials (VCs) and Verfiable Presentations (VPs) to verify access and encode +data. The following diagram depicts the preparation process for a DID document to be sent to and stored on the server: + +1. First, a cryptographic key is created or an existing key is selected. +2. The DID document is created that references the key. +3. A Verifiable Credential is created that includes the DID document. The VC is signed by an authorized key (when the + DID is first created, the server owner's key must sign the VC). +4. A Verifiable Presentation is created that includes the VC. The VP is signed by an authorized key (when the DID is + first created, the server owner's key must sign the VP). To mitigate replay attacks, the VP must also contain + specific proof parameters that can be retrieved from did-web-server. +5. If the submitted VP and VC are successfully verfied, the included DID document is stored on the server. + +![Component diagram for creating and updating a DID document](/figures/did-creation-components.svg) + ### Create key Every DID requires a public private key pair. We can reuse the previous command to create another key pair for the new diff --git a/docs/src/content/docs/index.md b/docs/src/content/docs/index.md index 66336a9..d141f30 100644 --- a/docs/src/content/docs/index.md +++ b/docs/src/content/docs/index.md @@ -17,12 +17,13 @@ did-web-server uses DIDs, [Verifiable Credentials (VCs)](https://w3c.github.io/v Presentations (VPs) to verify access and encode identifier data. No API tokens, usernames, or passwords are required to interact with the service. -The following diagram depicts the context in which did-web-server operates. A wallet manages the keys that control an -identifier. Only via these keys can DID documents on did-web-server be modified and updated. The main components that -did-web-server interacts with are DID resolvers. They retrieve DID documents from the server via the standardized +The following diagram depicts the system context in which did-web-server operates. The context includes additional +actors and systems that are not part of did-web-server. A wallet manages the keys that control an identifier. Only via +these keys can DID documents on did-web-server be modified and updated. The main components that did-web-server +interacts with are DID resolvers. They retrieve DID documents from the server via the standardized [did:web](https://w3c-ccg.github.io/did-method-web/) DID method. -![Architecture diagram](/figures/did-web-server-context.svg) +![System Context Diagram](/figures/did-web-server-context.svg) ## Tutorial