diff --git a/documentation/docs/get-started/api-server-get-started/basic-operations.md b/documentation/docs/get-started/api-server-get-started/basic-operations.md index 7a54a432..b6b8733a 100644 --- a/documentation/docs/get-started/api-server-get-started/basic-operations.md +++ b/documentation/docs/get-started/api-server-get-started/basic-operations.md @@ -27,123 +27,7 @@ Or if you try with the API docs, you can add the API key to the [Authentication ## Create identifier -### [Optional] Using https for localhost by using ngrok - -To try this locally, you need to create a secure tunnel to your `localhost:3332`(the VCkit API server). You can use [**ngrok**](https://ngrok.com/) to do this. After you have installed and registered ngrok, you can run this command to create a secure tunnel to your localhost. - -```bash -ngrok http 3332 -``` - -![ngrok](/img/ngrok.png) - -### Create a DID web - -To create an identifier, we use this [`/didManagerCreate`](http://localhost:3332/api-docs#post-/didManagerCreate) endpoint. - -#### Request body: - -```json -{ - "alias": "example.com", //replace by your domain - "provider": "did:web", //you can use other providers, in this case we use did:web - "kms": "local", - "options": { - "keyType": "Ed25519" - } -} -``` - -The `alias` is the domain name that you will store a [DID document](/docs/get-started/api-server-get-started/basic-operations#did-document) for your DID web after creation, your domain must be enabled with HTTPS. Or you can choose the easy way by using the ngrok domain that you created in the previous optional step to create your local DID web, with DID document is generated automatically. But the ngrok domain will be expired after a while, so the DID web will be invalid. - -```json -{ - "alias": "e3a8-42-117-186-253.ngrok-free.app", // Your ngrok domain - "provider": "did:web", - "kms": "local", - "options": { - "keyType": "Ed25519" - } -} -``` - -#### Expected response: - -```json -{ - "did": "did:web:example.com", - "controllerKeyId": "b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e", - "keys": [ - { - "type": "Ed25519", - "kid": "b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e", - "publicKeyHex": "b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e", - "meta": { - "algorithms": ["EdDSA", "Ed25519"] - }, - "kms": "local" - } - ], - "services": [], - "provider": "did:web", - "alias": "example.com" -} -``` - -### DID document - -After creating your DID web, you need to generate a DID document for your domain by this API - -```curl -# Request -curl --location 'localhost:3332/.well-known/did.json' \ ---header 'Host: example.com' -``` - -```jsonc -# Response -{ - "@context": [ - "https://www.w3.org/ns/did/v1", - "https://w3id.org/security/suites/jws-2020/v1" - ], - "id": "did:web:example.com", - "verificationMethod": [ - { - "id": "did:web:example.com#b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e-key-0", - "type": "JsonWebKey2020", - "controller": "did:web:example.com", - "publicKeyJwk": { - "kty": "OKP", - "crv": "Ed25519", - "x": "sRFBatRait94T8quf3rJOdigzwB-rpnt76Mzk7GLHR4" - } - }, - { - "id": "did:web:example.com#b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e-key-1", - "type": "JsonWebKey2020", - "controller": "did:web:example.com", - "publicKeyJwk": { - "kty": "OKP", - "crv": "X25519", - "x": "BnKiBQSLJTWOoGaAeWiKxwTprxnJuhY5ijr8lY3n6FU" - } - } - ], - "authentication": [ - "did:web:example.com#b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e-key-0", - "did:web:example.com#b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e-key-1" - ], - "assertionMethod": [ - "did:web:example.com#b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e-key-0", - "did:web:example.com#b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e-key-1" - ], - "keyAgreement": [], - "service": [] -} -``` - -After you have the DID document, you need to deploy it to your domain with the path `/.well-known/did.json`. +**[Go here to create a `did:web`](/docs/get-started/did-web/how-to-create/hosting-did-web)** ## Issue a VC diff --git a/documentation/docs/get-started/did-web/_category_.json b/documentation/docs/get-started/did-web/_category_.json new file mode 100644 index 00000000..9df618e3 --- /dev/null +++ b/documentation/docs/get-started/did-web/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "DIDs and did:web", + "position": 5, + "link": { + "type": "generated-index", + "description": "Learn about Decentralised Identifiers (DIDs), how they enable self-sovereign digital identities, and how to create, manage, and host a DID:web identifier using VCkit." + } +} diff --git a/documentation/docs/get-started/did-web/how-to-create/_category_.json b/documentation/docs/get-started/did-web/how-to-create/_category_.json new file mode 100644 index 00000000..58f6fde3 --- /dev/null +++ b/documentation/docs/get-started/did-web/how-to-create/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Creating and Hosting a did:web Identifier", + "position": 2, + "link": { + "type": "generated-index", + "description": "This section will guide you through the process of creating, retrieving, and hosting a did:web identifier using VCkit. Project VCkit provides users with three ways to create and manage a did:web. Whether you're looking to use our preconfigured setup, host locally, or use your own domain, we've got you covered." + } +} diff --git a/documentation/docs/get-started/did-web/how-to-create/hosting-did-web.md b/documentation/docs/get-started/did-web/how-to-create/hosting-did-web.md new file mode 100644 index 00000000..f48781d6 --- /dev/null +++ b/documentation/docs/get-started/did-web/how-to-create/hosting-did-web.md @@ -0,0 +1,154 @@ +--- +sidebar_label: 'Using Your Own Domain or Ngrok' +sidebar_position: 2 +--- + +import Disclaimer from './../../../\_disclaimer.mdx'; + +# Create and Host a did:web Identifier + + + +## Section 1: Domain Setup and Importance of HTTPS + +### Why HTTPS is Essential + +For `did:web` identifiers, it's crucial that your domain is HTTPS-enabled. The DID method `did:web` relies on web infrastructure to serve the DID Document from a domain. Without HTTPS, your DID Document won't be considered secure or verifiable by external services and clients. + +Most browsers and services enforce HTTPS to ensure that data exchanged between servers and users remains encrypted and protected from interception. + +### Preparing Your Domain + +To create a `did:web`, you'll need: + +- A registered domain (e.g., `example.com`). +- The ability to host files on that domain. +- HTTPS enabled on your domain, typically via SSL certificates (e.g., via Let's Encrypt or other providers). + +Once your domain is set up with HTTPS, you can proceed to create and host your `did:web` identifier. + +#### Alternative: Testing with Ngrok (Without a Domain) + +If you don't have a domain but want to test the process locally, you can use [**ngrok**](https://ngrok.com/download) to create a secure HTTPS tunnel to your localhost. Ngrok temporarily exposes your local server to the internet, giving you a unique URL for testing. + +**Steps to Use Ngrok:** + +1. Install and register [**ngrok**](https://ngrok.com/download). +2. Run the following command to create a secure tunnel to your `localhost:3332` (VCkit API server): + + ```bash + ngrok http 3332 + ``` + +## Section 2: Creating a `did:web` and DID Document + +In this guide, we'll use the VCkit API server to create a `did:web` identifier. Before proceeding, ensure that you have the API server set up and running. **[Go here to set up the API server](/docs/get-started/api-server-get-started/installation)** + +Additionally, you will need to authenticate with the API server to make the necessary requests. **[Go here for how to authenticate](/docs/get-started/api-server-get-started/basic-operations#authentication)** + +Once your API server is running, you can follow the steps below to create and host your `did:web` identifier. + +To create a `did:web` identifier, you’ll use the VCkit API to generate a DID and the corresponding DID Document. This can later be hosted on your own domain or tested using a tunneling service like **ngrok**. + +### Create a DID:web Identifier + +Use the [`/didManagerCreate`](http://localhost:3332/api-docs#post-/didManagerCreate) endpoint to create a `did:web` identifier. + +#### Request Body Example: + +```json +{ + "alias": "example.com", //replace with your domain + "provider": "did:web", + "kms": "local", + "options": { + "keyType": "Ed25519" + } +} +``` + +- **alias**: Your domain name, or use the Ngrok URL (e.g., e3a8-42-117-186-253.ngrok-free.app) for local testing. +- **provider**: Set to did:web for this example. +- **kms**: Key management system, set to "local". +- **keyType**: Use the Ed25519 key type. + +#### Response Body Example: + +``` +{ + "did": "did:web:example.com", + "controllerKeyId": "b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e", + "keys": [ + { + "type": "Ed25519", + "kid": "b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e", + "publicKeyHex": "b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e", + "meta": { + "algorithms": ["EdDSA", "Ed25519"] + }, + "kms": "local" + } + ], + "provider": "did:web", + "alias": "example.com" +} +``` + +### Generate the DID Document + +After creating your DID +, you need to generate the corresponding DID document, which must be hosted on your HTTPS-enabled domain or served via your Ngrok URL. + +#### Example CURL Request: + +``` +curl --location 'localhost:3332/.well-known/did.json' \ +--header 'Host: example.com' # or ngrok URL if testing locally +``` + +#### Example DID Document Response: + +``` +{ + "@context": [ + "https://www.w3.org/ns/did/v1", + "https://w3id.org/security/suites/jws-2020/v1" + ], + "id": "did:web:example.com", // or ngrok URL if testing locally + "verificationMethod": [ + { + "id": "did:web:example.com#b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e-key-0", + "type": "JsonWebKey2020", + "controller": "did:web:example.com", + "publicKeyJwk": { + "kty": "OKP", + "crv": "Ed25519", + "x": "sRFBatRait94T8quf3rJOdigzwB-rpnt76Mzk7GLHR4" + } + } + ], + "authentication": [ + "did:web:example.com#b111416ad45a8adf784fcaae7f7ac939d8a0cf007eae99edefa33393b18b1d1e-key-0" + ] +} +``` + +Once generated, the DID document needs to be placed at the following path: + +- **For domain**: `https://example.com/.well-known/did.json` +- **For Ngrok:** VCKit automatically serves the DID document at `http://localhost:3332/.well-known/did.json`. Since Ngrok points to your local server, you can access the DID document at `https://e3a8-42-117-186-253.ngrok-free.app/.well-known/did.json` for external testing. VCKit retrieves the domain from the Host header to determine which did:web to resolve, ensuring the correct DID document is served for your domain or Ngrok URL. + +:::important +If you are using an additional path in your DID (e.g., did:web:example.com:subpath), you must not use /.well-known. Instead, host the DID document directly at the additional path, like so: `https://example.com/subpath/did.json` +::: + +### Serving the DID Document with the Correct MIME Type + +When hosting your DID document (e.g., at `/.well-known/did.json`), it's essential to ensure the document is served with the correct MIME type. The appropriate MIME type ensures that clients and verifiers can correctly process your DID document. + +#### Correct MIME Type for DID Documents + +The recommended MIME type depends on the format of your DID document: + +- **For JSON DID Documents**: Use `application/did+json`. +- **For JSON-LD DID Documents**: Use `application/did+ld+json`. diff --git a/documentation/docs/get-started/did-web/how-to-create/seed-identifier.md b/documentation/docs/get-started/did-web/how-to-create/seed-identifier.md new file mode 100644 index 00000000..3cc0c2ff --- /dev/null +++ b/documentation/docs/get-started/did-web/how-to-create/seed-identifier.md @@ -0,0 +1,55 @@ +--- +sidebar_label: 'Preconfigured Setup: Seed Identifier Script' +sidebar_position: 1 +--- + +import Disclaimer from './../../../\_disclaimer.mdx'; + +# Preconfigured Setup: Seed Identifier Script + + + +## Overview + +The easiest way to create a `did:web` in Project VCkit is by using the **Seed Identifier Script**. This method automatically sets up a `did:web` pointing to the preconfigured GitHub Pages URL for Project VCkit. + +This setup is ideal for developers who need a quick and reliable `did:web` for testing or development without configuring custom hosting. + +## How to Use + +In this guide, we'll use CLI to seed the preconfigured identifier. Before proceeding, ensure that you have the CLI set up. **[Go here to set up the CLI](/docs/get-started/cli-get-started/installation)** + +**Run the Seed Identifier Script**: + Navigate to your project directory and run the following command: + +```bash +pnpm seed-identifier +``` + +:::note +The Docker Compose entrypoint includes a shell command to run the seed-identifier script automatically. +::: + +**Resulting DID** + +The script will generate a did:web that points to the following GitHub Pages URL: + +`did:web:uncefact.github.io:project-vckit:test-and-development` + +**What Happens** + +- The script imports the predefined identifier located in the repo at `/development/did-web-identifier`. + +- This identifier contains the public and private key pair, which is then imported into the local key management system (KMS). + +- The did:web document itself has already been generated and hosted at `https://uncefact.github.io/project-vckit/test-and-development/did.json`. + +## When to Use This Method + +### For Development and Testing + +If you're in the development phase and don't want the hassle of setting up your own domain or local server, this method gives you a preconfigured did:web that’s easy to use. + +### Quick Start for New Users + +New users can immediately start working with decentralised identity without any additional configuration. diff --git a/documentation/docs/get-started/did-web/introduction.md b/documentation/docs/get-started/did-web/introduction.md new file mode 100644 index 00000000..9bd5d2b6 --- /dev/null +++ b/documentation/docs/get-started/did-web/introduction.md @@ -0,0 +1,73 @@ +--- +sidebar_label: 'Crash Course' +sidebar_position: 1 +--- + +import Disclaimer from './../../\_disclaimer.mdx'; + +# Introduction + + + +Decentralised Identifiers (DIDs) are a new type of identifier that enable verifiable, self-sovereign digital identities. Unlike traditional identifiers (such as email addresses or usernames), DIDs are not controlled by a central authority, allowing decentralised identity management. + +A DID typically consists of a URI that resolves to a DID Document, which contains public keys, authentication methods, and service endpoints related to the DID. + +### DID Methods + +DIDs can be created using various methods (e.g., `did:key`, `did:ethr`, `did:web`), each with different use cases and underlying technologies. + +### DID Documents + +A DID Document contains cryptographic material and service endpoints. It's stored in a decentralised manner but can be resolved to retrieve relevant information. + +## What is did:web? + +`did:web` is a DID method that allows you to host a DID Document on a web domain. It's designed for use cases where existing web infrastructure (like domains and HTTPS) can be leveraged to create a decentralised identifier. + +### did:web Structure + +A `did:web` identifier is constructed based on a domain name. The structure is as follows: + +`did:web:` + +For example: + +- `did:web:example.com` points to a DID Document hosted at `https://example.com/.well-known/did.json`. +- `did:web:subdomain.example.com` would point to a DID Document at `https://subdomain.example.com/.well-known/did.json`. +- `did:web:subdomain.example.com:users:alice` would point to a DID Document at `https://subdomain.example.com/users/alice/did.json`. In this format, the additional path (users/alice) means the `.well-known` directory is not included, and the DID document is directly under the specified path + +### Advantages of did:web + +- **Ease of Adoption**: `did:web` requires no special blockchain infrastructure, making it easier for organisations with existing web domains to implement. +- **Decentralised Identity for the Web**: Since it uses the web's existing infrastructure, `did:web` is easily accessible and can leverage tools like TLS and DNS. +- **Ownership Control**: Domain owners maintain complete control over the associated DID by hosting their DID Document. + +### Limitations of did:web + +- **DNS Dependence**: Since `did:web` relies on the DNS system, it is still somewhat centralised, depending on DNS providers and Certificate Authorities for HTTPS. +- **No Blockchain Backing**: Unlike blockchain-based DID methods, `did:web` does not have cryptographic immutability or tamper-evidence, making it less suited for certain trust-sensitive use cases. + +### How did:web Works + +1. **Creation of a did:web Identifier**: The DID identifier is derived from the domain name. For example, if you own the domain `example.com`, your DID identifier would be `did:web:example.com`. +2. **Hosting the DID Document**: By default, the DID Document must be hosted in the `.well-known` directory on your domain. For example: + + - `https://example.com/.well-known/did.json` + + However, if you're using a custom path, the document can be hosted at any location on your domain. In this case, the `did:web` identifier would reflect the custom path. For instance, if you host the document at `https://example.com/custom-path/did.json`, your DID identifier would be `did:web:example.com:custom-path`. + +3. **MIME Type Requirement** + When hosting the DID Document, it is essential to serve it with the correct MIME type to ensure that it is recognised and processed correctly by clients. The MIME type for DID documents is: + + - For JSON DID Documents: application/did+json + - For JSON-LD DID Documents: application/did+ld+json + +4. **HTTPS Requirement**: The domain must serve content over HTTPS. This ensures secure and encrypted communication when resolving the DID Document. Hosting it without HTTPS would result in non-compliance with did:web standards. + +5. **DID Resolution**: When someone queries the DID (e.g., `did:web:example.com`), the DID resolution process fetches the DID Document from the appropriate path, such as `https://example.com/.well-known/did.json` or a custom path. The DID Document is returned and used for cryptographic operations such as verification and authentication. + +### Use Cases for did:web + +- Organisations wanting decentralised identity management with existing web domains. +- Projects requiring decentralised identifiers without the complexity of blockchain-based DIDs. diff --git a/documentation/docs/get-started/intro.md b/documentation/docs/get-started/intro.md index 2ba3b85e..712a9358 100644 --- a/documentation/docs/get-started/intro.md +++ b/documentation/docs/get-started/intro.md @@ -17,7 +17,13 @@ This guide will walk you through getting started with VCkit. There are 4 differe The list of methods below has been arranged in order from simple to complex. Each method will have different advantages and disadvantages. We recommend starting with Demo Explorer so you can easily try out VCkit. +:::note +Each method includes steps to create a DID. + +If you're already familiar with DIDs, feel free to proceed. If not, no worries! [Go here for a quick crash course](category/dids-and-didweb). +::: + - [VCkit Demo Explorer](/docs/category/demo-explorer) - [VCkit API Server](/docs/category/api-server) - [VCkit CLI](/docs/category/cli) -- [VCkit library](/docs/category/vckit-library) \ No newline at end of file +- [VCkit library](/docs/category/vckit-library)