From 40989d551a9248d1cea728f5140d2adf5248d4f9 Mon Sep 17 00:00:00 2001 From: mikeplotean <101570226+mikeplotean@users.noreply.github.com> Date: Fri, 24 Nov 2023 22:06:31 +0200 Subject: [PATCH] docs: dids - minor readme adjustments (#26) --- README.md | 22 +-- waltid-crypto/README.md | 4 +- waltid-did/README.md | 369 ++++++++++++++++++++++++++++++++++++++++ waltid-did/readme.md | 107 ------------ 4 files changed, 372 insertions(+), 130 deletions(-) create mode 100644 waltid-did/README.md delete mode 100644 waltid-did/readme.md diff --git a/README.md b/README.md index 3e5d45f9e..78d4578b6 100644 --- a/README.md +++ b/README.md @@ -21,24 +21,4 @@ docker run -p 7000:7000 waltid/issuer --webHost=0.0.0.0 --webPort=7000 --baseUrl ```shell docker build -t waltid/verifier -f docker/verifier.Dockerfile . docker run -p 7001:7001 waltid/verifier --webHost=0.0.0.0 --webPort=7001 --baseUrl=http://localhost:7001 -``` - -### (Optional) Setup Vault - -#### apt - -```shell -wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg -echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo -tee /etc/apt/sources.list.d/hashicorp.list -sudo apt update && sudo apt install vault -``` - -```shell -vault server -dev -dev-root-token-id="dev-only-token" -``` -#### Docker - -```shell -docker run -p 8200:8200 --cap-add=IPC_LOCK -e VAULT_DEV_ROOT_TOKEN_ID=myroot -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 hashicorp/vault -``` +``` \ No newline at end of file diff --git a/waltid-crypto/README.md b/waltid-crypto/README.md index e69e61abc..ac311c639 100644 --- a/waltid-crypto/README.md +++ b/waltid-crypto/README.md @@ -306,7 +306,7 @@ For usage examples on _create_, _sign_, _verify_, _import_ and _export_ function ✓ - + @@ -338,7 +338,7 @@ For usage examples on _create_, _sign_, _verify_, _import_ and _export_ function ✓ - + diff --git a/waltid-did/README.md b/waltid-did/README.md new file mode 100644 index 000000000..bdc355a17 --- /dev/null +++ b/waltid-did/README.md @@ -0,0 +1,369 @@ +
+

Kotlin Multiplatform DID library

+ by walt.id + +[![CI/CD Workflow for walt.id did]()]() + +Join community! + + +Follow @walt_id + + + +
+ +## What it provides + +_**walt.id did**_ library provides functionality for registering and resolving DIDs. +There are 2 options offered for each function: + +- universal - relies on the universal DID registrar / resolver, e.g.: + - uni-registrar - https://uniregistrar.io + - uni-resolver - https://dev.uniresolver.io +- local - provides local implementations of DID methods + +For the cryptographic part, _**walt.id did**_ library relies on _**walt.id crypto**_ library. + +The top-level interface to access the registrar / resolver functions is provided +by the `DidService` singleton. +The complete class hierarchy can be viewed in the [class diagram](did-lib_class.drawio.png). + +## How to use it + +### Register DID + +Create the key and register the Did: + +```kotlin +val options = DidWebCreateOptions( + domain = "localhost:3000", + path = "/path/to/did.json", + keyType = KeyType.Ed25519 +) +val didResult = DidService.register(options = options) +``` + +Register the Did with a given key: + +```kotlin +val key = LocalKey.generate(KeyType.Ed25519) +val options = DidKeyCreateOptions( + useJwkJcsPub = true +) +val didResult = DidService.register( + method = "key", + key = key, + options = options +) +``` + +Both calls return a `DidResult` object: + +```kotlin +data class DidResult( + val did: String, + val didDocument: DidDocument +) +``` + +where `did` - is the Did url string, while `didDocument` is the corresponding +DidDocument represented as a key-value pair, having the key as a `String` and +value as a `JsonElement`. + +### Resolve DID + +Resolve the Did url to a Did Document: + +```kotlin +val did = "did:web:localhost:3000" +val didDocumentResult = DidService.resolve(did = did) +val document = didDocumentResult.getOrNull() +``` + +Resolve the Did url to its public Key: + +```kotlin +val did = "did:key:zmYg9bgKmRiCqTTd9MA1ufVE9tfzUptwQp4GMRxptXquJWw4Uj5cqKBi2vyiwwxC3v7ixvJ8SB9DvDdrK7UemySWDPhvHhUcZ7pgtZtFchLtzK4YC" +val keyResult = DidService.resolveToKey(did = did) +val key = keyResult.getOrNull() +``` + +Both calls return the result using the _operation result pattern_, +the data being wrapped by the `Result` object. This allows checking for +a successful operation and handling the result accordingly. + +The Did Document data is represented as `JsonObject`. The key data is +represented as **_walt.id crypto_** `Key`. + + +## Local DID operations implemented natively + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodKeyFeature
createregisterresolve
keyed25519✓‐✓
secp256k1✓‐✓
secp256r1✓‐✓
rsa✓‐✗
jwked25519✓‐✓
secp256k1✓‐✓
secp256r1✓‐✓
rsa✓‐✗
webed25519✓✗✓
secp256k1✓✗✓
secp256r1✓✗✓
rsa✓✗✗
cheqded25519✓✓✓
ebsisecp256r1✗✗✗
iotaed25519✗✗✗
+ +## Remote DID operations by 3d party services (fallback) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodKeyFeature
createresolve
keyed25519✓✓
secp256k1✓✓
secp256r1✓✓
rsa✓✓
jwked25519✓✓
secp256k1✓✓
secp256r1✓✓
rsa✓✓
webed25519✓✓
secp256k1✓✓
secp256r1✓✓
rsa✓✓
cheqded25519✓✓
ebsisecp256r1✓✓
iotaed25519✓✓
\ No newline at end of file diff --git a/waltid-did/readme.md b/waltid-did/readme.md deleted file mode 100644 index 3bee0d80e..000000000 --- a/waltid-did/readme.md +++ /dev/null @@ -1,107 +0,0 @@ -
-

walt.id did-lib - Kotlin multiplatform library

- by walt.id - -[![CI/CD Workflow for walt.id did]()]() - -Join community! - - -Follow @walt_id - - - -
- -## Getting started - -_**walt.id did**_ library provides functionality for registering and resolving DIDs. -There are 2 options offered for each function: - -- universal - relies on the universal DID registrar / resolver, e.g.: - - uni-registrar - https://uniregistrar.io - - uni-resolver - https://dev.uniresolver.io -- local - provides local implementations of DID methods - -For the cryptographic part, _**walt.id did**_ library relies on _**walt.id crypto**_ library. - -## Class diagram - -![walt.id did class diagram](did-lib_class.drawio.png) - -The top-level interface to access the registrar / resolver functions is provided -by the `DidService` singleton. - -## Usage examples - -### Register DID - -Create the key and register the Did: - -```kotlin -val options = DidWebCreateOptions( - domain = "localhost:3000", - path = "/path/to/did.json", - keyType = KeyType.Ed25519 -) -val didResult = DidService.register(options = options) -``` - -Register the Did with the given key: - -```kotlin -val key = LocalKey.generate(KeyType.Ed25519) -val options = DidKeyCreateOptions( - useJwkJcsPub = true -) -val didResult = DidService.register( - method = "key", - key = key, - options = options -) -``` - -Both calls return a `DidResult` object: - -```kotlin -data class DidResult( - val did: String, - val didDocument: DidDocument -) -``` - -where `did` - is the Did url string, while `didDocument` is the corresponding -DidDocument represented as a key-value pair, having the key as a `String` and -value as a `JsonElement`. - -Currently available local did methods are: -`key`, `web`, `jwk`. - -Currently available universal did methods are: -`btcr`, `cheqd`, `ebsi`, `ethr`, `ion`, `jwk`, `key`, -`oyd`, `sov`, `v1`, `web`. - -### Resolve DID - -Resolve the Did url to a Did Document: - -```kotlin -val did = "did:web:localhost:3000" -val didDocumentResult = DidService.resolve(did = did) -val document = didDocumentResult.getOrNull() -``` - -Resolve the Did url to its public Key: - -```kotlin -val did = "did:key:zmYg9bgKmRiCqTTd9MA1ufVE9tfzUptwQp4GMRxptXquJWw4Uj5cqKBi2vyiwwxC3v7ixvJ8SB9DvDdrK7UemySWDPhvHhUcZ7pgtZtFchLtzK4YC" -val keyResult = DidService.resolveToKey(did = did) -val key = keyResult.getOrNull() -``` - -Both calls return the result using the _operation result pattern_, -the data being wrapped by the `Result` object. This allows checking for -a successful operation and handling the result accordingly. - -The Did Document data is represented as `JsonObject`. The key data is -represented as **_walt.id crypto_** `Key`.