From b57a6568f59f958e8d3ff9d54b0641c052571bb7 Mon Sep 17 00:00:00 2001 From: Gabe <7622243+decentralgabe@users.noreply.github.com> Date: Fri, 28 Jul 2023 10:27:29 -0700 Subject: [PATCH] Update READMEs, docs, add how-tos section, first how-to for DIDs (#607) * how tos * table of docs * consolidate and clean up docs * remove templating * did tutorial --- README.md | 169 +++++++----------- cmd/ssiservice/main.go | 3 +- config/README.md | 19 -- doc/README.md | 58 +++++- doc/config/kms.md | 27 +++ doc/{STORAGE.md => config/storage.md} | 2 +- doc/config/toml.md | 20 +++ doc/howto/credential.md | 0 doc/howto/did.md | 122 +++++++++++++ doc/howto/schema.md | 0 doc/howto/status.md | 0 doc/howto/verification.md | 0 doc/service/features.md | 19 ++ doc/{VERSIONING.md => service/versioning.md} | 0 doc/{VISION.md => service/vision.md} | 0 doc/{WEBHOOK.md => service/webhook.md} | 0 {sip => doc/sip}/README.md | 5 +- {sip => doc/sip}/sip_flow.png | Bin {sip => doc/sip}/sips/sip1/README.md | 0 {sip => doc/sip}/sips/sip2/README.md | 0 .../sip}/sips/sip2/assets/application.png | Bin .../sip}/sips/sip2/assets/manifest.png | Bin .../sip}/sips/sip2/assets/response.png | Bin .../sip}/sips/sip2/assets/toplevel.png | Bin {sip => doc/sip}/sips/sip3/README.md | 0 .../sip}/sips/sip3/assets/key-access.png | Bin {sip => doc/sip}/sips/sip4/README.md | 0 {sip => doc/sip}/sips/sip4/assets/diagram.png | Bin .../sip}/sips/sip4/assets/endpoints.png | Bin .../sip}/sips/sip4/assets/manifest.png | Bin {sip => doc/sip}/sips/sip5/README.md | 0 {sip => doc/sip}/sips/sip6/README.md | 0 {sip => doc/sip}/sips/sip7/README.md | 0 {sip => doc/sip}/sips/sip8/README.md | 0 .../sip8/assets/applicationsubmission.png | Bin {sip => doc/sip}/sips/sip9/README.md | 0 {sip => doc/sip}/sips/sip_template.md | 0 doc/swagger.yaml | 4 +- pkg/server/server.go | 47 +---- 39 files changed, 316 insertions(+), 179 deletions(-) delete mode 100644 config/README.md create mode 100644 doc/config/kms.md rename doc/{STORAGE.md => config/storage.md} (97%) create mode 100644 doc/config/toml.md create mode 100644 doc/howto/credential.md create mode 100644 doc/howto/did.md create mode 100644 doc/howto/schema.md create mode 100644 doc/howto/status.md create mode 100644 doc/howto/verification.md create mode 100644 doc/service/features.md rename doc/{VERSIONING.md => service/versioning.md} (100%) rename doc/{VISION.md => service/vision.md} (100%) rename doc/{WEBHOOK.md => service/webhook.md} (100%) rename {sip => doc/sip}/README.md (92%) rename {sip => doc/sip}/sip_flow.png (100%) rename {sip => doc/sip}/sips/sip1/README.md (100%) rename {sip => doc/sip}/sips/sip2/README.md (100%) rename {sip => doc/sip}/sips/sip2/assets/application.png (100%) rename {sip => doc/sip}/sips/sip2/assets/manifest.png (100%) rename {sip => doc/sip}/sips/sip2/assets/response.png (100%) rename {sip => doc/sip}/sips/sip2/assets/toplevel.png (100%) rename {sip => doc/sip}/sips/sip3/README.md (100%) rename {sip => doc/sip}/sips/sip3/assets/key-access.png (100%) rename {sip => doc/sip}/sips/sip4/README.md (100%) rename {sip => doc/sip}/sips/sip4/assets/diagram.png (100%) rename {sip => doc/sip}/sips/sip4/assets/endpoints.png (100%) rename {sip => doc/sip}/sips/sip4/assets/manifest.png (100%) rename {sip => doc/sip}/sips/sip5/README.md (100%) rename {sip => doc/sip}/sips/sip6/README.md (100%) rename {sip => doc/sip}/sips/sip7/README.md (100%) rename {sip => doc/sip}/sips/sip8/README.md (100%) rename {sip => doc/sip}/sips/sip8/assets/applicationsubmission.png (100%) rename {sip => doc/sip}/sips/sip9/README.md (100%) rename {sip => doc/sip}/sips/sip_template.md (100%) diff --git a/README.md b/README.md index 3f6d719d3..0f0233273 100644 --- a/README.md +++ b/README.md @@ -6,85 +6,56 @@ # ssi-service -A web service that exposes the ssi-sdk as an HTTP API. Support operations for Verifiable Credentials, Decentralized Identifiers and things Self Sovereign Identity! - -## Introduction -The Self Sovereign Identity Service (SSIS) facilitates all things relating to [DIDs](https://www.w3.org/TR/did-core/) -and [Verifiable Credentials](https://www.w3.org/TR/vc-data-model) - in a box! The service is a part of a larger -Decentralized Web Platform architecture which you can learn more about in our -[collaboration repo](https://github.com/TBD54566975/collaboration). +The Self Sovereign Identity Service (SSIS) is a RESTful web service that facilitates all things relating +to [DIDs](https://www.w3.org/TR/did-core/), +[Verifiable Credentials](https://www.w3.org/TR/vc-data-model) and their related standards-based interactions. Most of +the functionality in this service +relies upon the SSI primitives exposed in the [SSI-SDK](https://github.com/TBD54566975/ssi-sdk) project. ## Core Functionality -- Create and manage Decentralized Identifiers -- Create and manage Verifiable Credentials -- Credential Suspension -- Interacting with the standards around Verifiable Credentials such as - - Credential Revocations - - Applying for Credentials - - Exchanging Credentials - - Data Schemas (for credentials and other verifiable data) - -## Use Cases (more to come!) -### Business: Issuing Verifiable Credentials
-[Follow Tutorial](https://developer.tbd.website/blog/issue-verifiable-credential-manually) - -Steps to issue an Employment Status Credential: -1. Spin up and host the SSI-Service -2. Add the ability for your employees to click 'apply for a credential' on your internal EMS (should we show a front end button code example) -3. [Create an Issuer DID](https://github.com/TBD54566975/ssi-service/blob/eabbb2a58eec06ce3998d088811c4afc53026afd/integration/common.go#L38) for your business -4. [Create a Schema](https://github.com/TBD54566975/ssi-service/blob/eabbb2a58eec06ce3998d088811c4afc53026afd/integration/common.go#L90) -5. [Create a Credential Manifest](https://github.com/TBD54566975/ssi-service/blob/main/integration/common.go#L180) -6. [Submit a Credential Application](https://github.com/TBD54566975/ssi-service/blob/eabbb2a58eec06ce3998d088811c4afc53026afd/integration/common.go#L199) - -## Configuration -Managed via: -[TOML](https://toml.io/en/) [file](config/dev.toml) - -There are sets of configuration values for the server (e.g. which port to listen on), the services (e.g. which database to use), -and each service. Each service may define specific configuration, such as which DID methods are enabled for the DID -service. - -### Key Management +- Lifecycle management for Decentralized Identifiers + - Multiple local, web, and blockchain methods supported +- Create and manage Verifiable Credentials + - Multiple securing mechanisms + - Data schemas using JSON Schema + - Lifecycle management with credential status (revocation, suspension, etc.) +- More robust DID and Verifiable Credential interactions such as... + - Enabling the application of credentials + - Verifying sets of credentials with custom logic + - Linking a DID to a web domain + - Integration into your existing systems with webhooks + - Trust management +- And much more! -SSI-service can store keys that are used to digitally sign credentials (and other data). All such keys are encrypted at -the application before being stored using a MasterKey (a.k.a. a Key Encryption Key or KEK). The MasterKey can be -generated automatically during boot time, or we can use the MasterKey housed in an external Key -Management System (KMS) like GCP KMS or AWS KMS. +## Documentation -For production deployments, using external KMS is strongly recommended. +### Vision, Features, and Development -To use an external KMS: -1. Create a symmetric encryption key in your KMS. You MUST select the algorithm that uses AES-256 block cipher in Galois/Counter Mode (GCM). At the time of writing, this is the only algorithm supported by AWS and GCP. -2. Set the `master_key_uri` field of the `[services.keystore]` section using the format described in [tink](https://github.com/google/tink/blob/9bc2667963e20eb42611b7581e570f0dddf65a2b/docs/KEY-MANAGEMENT.md#key-management-systems) -(we use the tink library under the hood). -3. Set the `kms_credentials_path` field of the `[services.keystore]` section to point to your credentials file, according to [this section](https://github.com/google/tink/blob/9bc2667963e20eb42611b7581e570f0dddf65a2b/docs/KEY-MANAGEMENT.md#credentials). -4. Win! +The vision for the project is laid out in [this document](doc/service/vision.md). -To use a randomly generated encryption key (NOT RECOMMENDED FOR ANY PRODUCTION ENVIRONMENT): -1. Make sure that `master_key_uri` and `kms_credentials_path` of the `[services.keystore]` section are not set. +The project follows a proposal-based improvement format called [SIPs, outlined here](sip/README.md). -Note that at this time, we do not currently support rotating the master key. +Please [join Discord](https://discord.com/invite/tbd), or open an [issue](https://github.com/TBD54566975/ssi-service/issues) if you are interested in helping shape the future of the +project. -### Steps for SSI-Service to consume its configuration: -1. On startup: SSI-Service loads default values into the SSIServiceConfig -2. Checks for a TOML config file: -- If exists...load toml file -- If does not exist...it uses a default config defined in the code inline -3. Finally, it loads the config/.env file and adds the env variables defined in this file to the final SSIServiceConfig +### API Documentation -### Authentication and Authorization +API documentation is generated using [Swagger](https://swagger.io/). The most recent +docs [can be found here](doc/swagger.yaml). -The ssi server uses the Gin framework from Golang, which allows various kinds of middleware. Look in `pkg/middleware/Authentication.go` and `pkg/middleware/Authorization.go` for details on how you can wire up authentication and authorization for your use case. +When running the service you can find API documentation at: `http://localhost:8080/swagger/index.html` -## Pre-built images to use +**Note:** Your port may differ; swagger docs are hosted on the same endpoint as the ssi service itself. -There are pre-build images built by github actions on each merge to the main branch, which you can access here: -https://github.com/orgs/TBD54566975/packages?repo_name=ssi-service +### How To's +We have a set of tutorials and how-to documents, instructing you on how to create a DID, issue your first credential, +and more! The docs can be found [in our docs here](doc/README.md). ## Build & Test +### Local Development This project uses [mage](https://magefile.org/), please view [CONTRIBUTING](https://github.com/TBD54566975/ssi-service/blob/main/CONTRIBUTING.md) for more information. @@ -101,28 +72,61 @@ A utility is provided to run _clean, build, lint, and test_ in sequence with: mage cblt ``` +### Continuous Integration + +CI is managed via [GitHub Actions](https://github.com/TBD54566975/ssi-service/actions). Actions are triggered to run for +each Pull Request, and on merge to `main`. +You can run CI locally using a tool like [act](https://github.com/nektos/act). + ## Deployment The service is packaged as a [Docker container](https://www.docker.com/), runnable in a wide variety of environments. +There are pre-build images built by GitHub Actions on each merge to the `main` branch, +which [you can access here](https://github.com/orgs/TBD54566975/packages?repo_name=ssi-service). + [Docker Compose](https://docs.docker.com/compose/) is used for simplification and orchestration. To run the service, you can use the following command, which will start the service on port `8080`: + ```shell mage run ``` Or, you can run docker-compose yourself, building from source: + ```shell cd build && docker-compose up --build ``` To use the pre-published images: + ```shell cd build && docker-compose up -d ``` -## Health and Readiness Checks +## Using the Service + +### Configuration + +Managed via: +[TOML](https://toml.io/en/) [file](config/dev.toml). Configuration documentation and sample config +files [can be found here](config/README.md). + +There are sets of configuration values for the server (e.g. which port to listen on), the services (e.g. which database +to use), +and each service. Each service may define specific configuration, such as which DID methods are enabled for the DID +service. + +More information on configuration can be found in the [configuration section of our docs](doc/README.md). + +### Authentication and Authorization + +The SSI server uses the [Gin framework](https://github.com/gin-gonic/gin), which allows various kinds of middleware. +Look in `pkg/middleware/Authentication.go` and `pkg/middleware/Authorization.go` for details on how you can wire up +authentication and authorization for your use case. + +### Health and Readiness Checks Note: port 3000 is used by default, specified in `config.toml`, for the SSI Service process. If you're running via `mage run` or docker compose, the port to access will be `8080`. @@ -157,45 +161,6 @@ Run to check if all services are up and ready (credential, did, and schema): } ``` -## Continuous Integration - -CI is managed via [GitHub Actions](https://github.com/TBD54566975/ssi-service/actions). Actions are triggered to run -for each Pull Request, and on merge to `main`. You can run CI locally using a tool -like [act](https://github.com/nektos/act). - -## API Documentation -You can find all HTTP endpoints by checking out the swagger docs at: `http://localhost:8080/swagger/index.html` - -Note: Your port may differ; swagger docs are hosted on the same endpoint as the ssi service itself. - -## What's Supported? -- [x] [DID Management](https://www.w3.org/TR/did-core/) - - [x] [did:key](https://w3c-ccg.github.io/did-method-key/) - - [x] [did:web](https://w3c-ccg.github.io/did-method-web/) - - [x] [did:ion](https://identity.foundation/ion/) _Note: updates not yet supported_ - - [x] [did:pkh](https://w3c-ccg.github.io/did-method-pkh/) _Resolution only_ - - [x] [did:peer](https://identity.foundation/peer-did-method-spec/) _Resolution only_ -- [x] [Verifiable Credential Schema](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) Management -- [x] [Verifiable Credential](https://www.w3.org/TR/vc-data-model) Issuance & Verification - - [x] Signing and verification with [JWTs](https://w3c.github.io/vc-jwt/) - - [ ] Signing and verification with [Data Integrity Proofs](https://w3c.github.io/vc-data-integrity/) -- [x] Applying for Verifiable Credentials using [Credential Manifest](https://identity.foundation/credential-manifest/) -- [x] Requesting, Receiving, and the Validation of Verifiable Claims - using [Presentation Exchange](https://identity.foundation/presentation-exchange/) -- [x] Status of Verifiable Credentials using the [Status List 2021](https://w3c-ccg.github.io/vc-status-list-2021/) -- [x] [DID Well Known Configuration](https://identity.foundation/.well-known/resources/did-configuration/) documents -- [ ] Creating and managing Trust documents using [Trust Establishment](https://identity.foundation/trust-establishment/) - -## Vision, Features, and Development - -The vision for the project is laid out in [this document](doc/VISION.md). - -The project follows a proposal-based improvement format called [SIPs, outlined here.](sip/README.md). - -Please [join Discord](https://discord.com/invite/tbd), -or open an [issue](https://github.com/TBD54566975/ssi-service/issues) if you are interested in helping shape the future of the project. - - ## Project Resources | Resource | Description | diff --git a/cmd/ssiservice/main.go b/cmd/ssiservice/main.go index 560e07086..268635d6e 100644 --- a/cmd/ssiservice/main.go +++ b/cmd/ssiservice/main.go @@ -30,13 +30,12 @@ import ( // main godoc // // @title SSI Service API -// @description {{.Desc}} +// @description The Self Sovereign Identity Service: Managing DIDs, Verifiable Credentials, and more! // @contact.name TBD // @contact.url https://github.com/TBD54566975/ssi-service/issues // @contact.email tbd-developer@squareup.com // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html -// @version {{.SVN}} func main() { logrus.Info("Starting up...") diff --git a/config/README.md b/config/README.md deleted file mode 100644 index d43d82bb7..000000000 --- a/config/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# Configuration - -Configuration is managed using -a [TOML](https://toml.io/en/) [file](https://github.com/TBD54566975/ssi-service/blob/main/config/config.toml). There are -sets of configuration values for the server (e.g. which port to listen on), the services (e.g. which database to use), -and each service. - -Each service may define specific configuration, such as which DID methods are enabled for the DID service. - -# Usage - -The service, upon boot, looks for a file called `config.toml` to find its configuration. - -There are a number of configuration files in this directory provided as defaults. -Specifically, `config.toml` -is intended to be used when the service is run as a local go process. There is another -file, `compose.toml`, -which is intended to be used when the service is run via docker compose. To make this switch, it's recommended that one -renames the file to `config.toml` and then maintains the original `compose.toml` file as `local.toml` or similar. diff --git a/doc/README.md b/doc/README.md index e99d40779..8c4c21403 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,11 +1,57 @@ +# Docs + +Home for all content related to the SSI Service. ## Service Documentation -| Resource | Description | -|--------------------------------------------------------------------------------------|----------------------------------------------------| -| [Vision](https://github.com/TBD54566975/ssi-service/blob/main/doc/VISION.md) | Describes the vision for the SSI Service | -| [Versioning](https://github.com/TBD54566975/ssi-service/blob/main/doc/VERSIONING.md) | Describes versioning practices for the SSI Service | -| [Webhooks](https://github.com/TBD54566975/ssi-service/blob/main/doc/WEBHOOK.md) | Describes how to use webhooks in the SSI Service | -| [Storage](https://github.com/TBD54566975/ssi-service/blob/main/doc/STORAGE.md) | Describes alternatives for storage in SSI Service | +Service documentation is focused on explaining the "whys" and "hows" of the SSI Service. It is intended to be a +resource for developers and users of the SSI Service. + +| Resource | Description | +|----------------------------------------------------------------------------------------------|---------------------------------------------------| +| [Vision](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/vision.md) | Describes the vision for the service | +| [Versioning](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/versioning.md) | Describes versioning practices for the service | +| [Webhooks](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/webhook.md) | Describes how to use webhooks in the service | +| [Features](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/features.md) | Features currently supported by the service | + +## Service Improvement Proposals (SIPs) + +All feature proposal documents for the SSI Service follow a common format and are known as SSI Improvement Proposals or +SIPs. SIPs [have their own documentation which can be found here](https://github.com/TBD54566975/ssi-service/blob/main/doc/sip/README.md) + +## Configuration + +There are a few ways to configure the service. There are a few choices you can make, including which database to use, +which DID methods to enable, and which port to listen on. Read the docs below for more details! + +| Resource | Description | +|------------------------------------------------------------------------------------------------------------|----------------------------------------| +| [TOML Config Files](https://github.com/TBD54566975/ssi-service/blob/main/doc/config/toml.md) | Describes how to use TOML config files | +| [Using a Cloud Key Management Service](https://github.com/TBD54566975/ssi-service/blob/main/doc/config/kms.md) | Describes how to configure a KMS | +| [Storage](https://github.com/TBD54566975/ssi-service/blob/main/doc/service/storage.md) | Describes alternatives for storage by the service | + +## API Documentation + +API documentation is generated using [Swagger](https://swagger.io/). The most recent API docs file [can be found here](doc/swagger.yaml), which can be pasted into the [Swagger Editor](https://editor.swagger.io/) for interaction. + +When running the service you can find API documentation at: `http://localhost:8080/swagger/index.html` + +**Note:** Your port may differ; swagger docs are hosted on the same endpoint as the ssi service itself. + +## How To's + +How to documentation is focused on explaining usage of the SSI Service. It is intended to be a resource for users of +the SSI Service to get up to speed with its functionality. + +| Resource | Description | +|----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------| +| [Creating a DID](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/credential.md) | Get started with DID functionality | +| [Creating a Schema](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/schema.md) | Get started with schema functionality | +| [Issuing a Credential](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/credential.md) | Get started with credential issuance functionality | +| [Verify a Credential](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/verification.md) | Get started with credential verification functionality | +| [Revoke/Suspend a Credential](https://github.com/TBD54566975/ssi-service/blob/main/doc/howto/status.md) | Get started with credential status functionality | +| [[TODO] Requesting and Verifying Credentials with Presentation Exchange](https://github.com/TBD54566975/ssi-service/issues/606) | Get started with Presentation Exchange functionality | +| [[TODO] Accepting Applications for and Issuing Credentials using Credential Manifest](https://github.com/TBD54566975/ssi-service/issues/606) | Get started with Credential Manifest functionality | +| [[TODO] Creating a Well Known File for your DID](https://github.com/TBD54566975/ssi-service/issues/606) | Get started with DID Well Known functionality | diff --git a/doc/config/kms.md b/doc/config/kms.md new file mode 100644 index 000000000..13149e952 --- /dev/null +++ b/doc/config/kms.md @@ -0,0 +1,27 @@ + +### Key Management + +The service can store keys that are used to digitally sign credentials (and other data). All such keys are encrypted at +the application before being stored using a MasterKey (a.k.a. a Key Encryption Key or KEK). The MasterKey can be +generated automatically during boot time, or we can use the MasterKey housed in an external Key +Management System (KMS) like GCP KMS or AWS KMS. + +For production deployments, using external KMS is strongly recommended. + +To use an external KMS: + +1. Create a symmetric encryption key in your KMS. You MUST select the algorithm that uses AES-256 block cipher in + Galois/Counter Mode (GCM). At the time of writing, this is the only algorithm supported by AWS and GCP. +2. Set the `master_key_uri` field of the `[services.keystore]` section using the format described + in [tink](https://github.com/google/tink/blob/9bc2667963e20eb42611b7581e570f0dddf65a2b/docs/KEY-MANAGEMENT.md#key-management-systems) + (we use the tink library under the hood). +3. Set the `kms_credentials_path` field of the `[services.keystore]` section to point to your credentials file, + according + to [this section](https://github.com/google/tink/blob/9bc2667963e20eb42611b7581e570f0dddf65a2b/docs/KEY-MANAGEMENT.md#credentials). +4. Win! + +To use a randomly generated encryption key (NOT RECOMMENDED FOR ANY PRODUCTION ENVIRONMENT): + +1. Make sure that `master_key_uri` and `kms_credentials_path` of the `[services.keystore]` section are not set. + +Note that at this time, we do not currently support rotating the master key. \ No newline at end of file diff --git a/doc/STORAGE.md b/doc/config/storage.md similarity index 97% rename from doc/STORAGE.md rename to doc/config/storage.md index 34420f9c4..7ba5c2cab 100644 --- a/doc/STORAGE.md +++ b/doc/config/storage.md @@ -68,7 +68,7 @@ For a working example, see this [dev.toml file](https://github.com/TBD54566975/s ## Implementing a New Storage Provider -You need to implement the [ServiceStorage interface](../pkg/storage/storage.go), similar to how [Redis](../pkg/storage/redis.go) +You need to implement the [ServiceStorage interface](../../pkg/storage/storage.go), similar to how [Redis](../../pkg/storage/redis.go) is implemented. For an example, see [this PR](https://github.com/TBD54566975/ssi-service/pull/590/files#diff-606358579107e7ad1221525001aed8c776a141d4cc5aab9ef7a3ddbcec10d9f9) which introduces the SQL based implementation. diff --git a/doc/config/toml.md b/doc/config/toml.md new file mode 100644 index 000000000..0abb04b61 --- /dev/null +++ b/doc/config/toml.md @@ -0,0 +1,20 @@ +# TOML Config File +Config is managed using a [TOML](https://toml.io/en/) [file](https://github.com/TBD54566975/ssi-service/blob/main/config/config.toml). There are sets of configuration values for the server +(e.g. which port to listen on), the services (e.g. which database to use), and each service. + +Each service may define specific configuration, such as which DID methods are enabled for the DID service. + +## Usage + +How it works: +1. On startup: SSI-Service loads default values into the `SSIServiceConfig` +2. Checks for a TOML config file: + - If exists...load toml file + - If does not exist...it uses a default config defined in the code inline +3. Loads the `config/.env` file and adds the env variables defined in this file to the final `SSIServiceConfig` + +There are a number of configuration files in this directory provided as defaults. +Specifically, `config.toml`is intended to be used when the service is run as a local go process. There is another +file, `compose.toml`, which is intended to be used when the service is run via docker compose. To make this switch, +it's recommended that one renames the file to `config.toml` and then maintains the original `compose.toml` file as +`local.toml` or similar. diff --git a/doc/howto/credential.md b/doc/howto/credential.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/howto/did.md b/doc/howto/did.md new file mode 100644 index 000000000..414134c25 --- /dev/null +++ b/doc/howto/did.md @@ -0,0 +1,122 @@ +# How To: Create a DID + +## Background + +A [DID (Decentralized Identifier)](https://www.w3.org/TR/did-core/) is a unique identifier that can be used to identify a person, organization, or thing. DIDs are associated with documents called DID Documents. These documents contain +cryptographic key material, service endpoints, and other useful information. + +DIDs are a core component of SSI (Self-Sovereign Identity) systems. DIDs are specified according to "methods" which +define how the DID is created and how it can be used. A list of existing [DID methods can be found here](https://www.w3.org/TR/did-spec-registries/#did-methods). + +Importantly, DIDs in the SSI Service are _fully custodial_. This means the private keys associated with DID Documents are managed by the service and never leave its boundaries. For some DID methods, such as `did:web` it's possible to add multiple keys to the DID document, and it's possible for these additional keys to be added outside the service. This is a more advanced concept that the service may support in the future. + +## What DID Methods are There? + +The SSI Service supports a number of DID methods, including... + +* [DID Key](https://w3c-ccg.github.io/did-method-key/) a self-resolving method great for testing +* [DID Web](https://w3c-ccg.github.io/did-method-web/) a method designed to be hosted on your own domain +* [DID ION](https://identity.foundation/sidetree/spec/#value-locking) a Layer 2 Bitcoin method based on the Sidetree protocol. + +At runtime, the you can enable and disable which methods the service supports. Learn more about this by reading our [documentation on configuration](../README.md). + +Once the service is running you can see which DID methods are enabled by sending a `GET` request to `/v1/dids`. + +Upon a successful request you should see a response such as: + +```json +{ + "method": [ + "key", + "web" + ] +} +``` + +## Creating A DID + +You can create a DID by sending a `PUT` request to the `/v1/dids/{method}` endpoint. The request body needs two pieces of information: a method and a key type. The method must be supported by the service, and the key type must be supported by the method. You can find out more specifics about what each method supports [by looking at the SDK](https://github.com/TBD54566975/ssi-sdk/tree/main/did). Certain methods may support additional properties in an optional `options` fields. + +For now let's keep things simple and create a new `did:key` with the key type [`Ed25519`](https://ed25519.cr.yp.to/), a widely respected key type using [ellicptic curve cryptography](https://en.wikipedia.org/wiki/Elliptic-curve_cryptography). + +**Create DID Key Request** + +`PUT` to `/v1/dids/key` + +```json +{ + "keyType": "Ed25519" +} +``` + +If successful, you should see a response such as... + +```json +{ + "did": { + "@context": [ + "https://www.w3.org/ns/did/v1", + "https://w3id.org/security/suites/jws-2020/v1" + ], + "id": "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g", + "verificationMethod": [ + { + "id": "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g#z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g", + "type": "JsonWebKey2020", + "controller": "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g", + "publicKeyJwk": { + "kty": "OKP", + "crv": "Ed25519", + "x": "7VpY8ilUvfIgUVf9DOO58BD1kQKPN_NDrNvr8qyK-2M", + "alg": "EdDSA", + "kid": "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g" + } + }, + { + "id": "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g#z6LSgpucz3mqZYRRzBpx8zGtWQAKSkyLqfQMEpxr2PVaRX8V", + "type": "JsonWebKey2020", + "controller": "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g", + "publicKeyJwk": { + "kty": "OKP", + "crv": "X25519", + "x": "TIcWJZVD0_TUHYzm9eyc1s5bD3EmrjTlVQfaHDfrazo", + "alg": "X25519", + "kid": "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g" + } + } + ], + "authentication": [ + "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g#z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g" + ], + "assertionMethod": [ + "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g#z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g" + ], + "keyAgreement": [ + "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g#z6LSgpucz3mqZYRRzBpx8zGtWQAKSkyLqfQMEpxr2PVaRX8V" + ], + "capabilityInvocation": [ + "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g#z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g" + ], + "capabilityDelegation": [ + "did:key:z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g#z6MkvRnaDoRv4qn6scLAE2RVAv1Yj42S9HZkkJTYB8Lm2U5g" + ] + } +} +``` + +which is a fully complaint `did:key` document [according to its specification](https://w3c-ccg.github.io/did-method-key/). + +Now that you have a DID you can begin to use it with other pieces of the service, such as by [issuing a credential](credential.md). + +## Getting DIDs + +Once you've created muliple DIDs, you can view all DIDs under a given method by making a `GET` request to the method's endpoint, such as `/v1/dids/key`. + +You can get a specific DID's document by making a `GET` request to the method's endpoint, such as `/v1/dids/key/{did}`. + +## DIDs Outside the Service + +The [universal resolver](https://github.com/decentralized-identity/universal-resolver) is a project at the [Decentralized Identity Foundation](https://identity.foundation/) aiming to enable the resolution of _any_ DID Document. The service, when run with [Docker Compose, runs a select number of these drivers (and more can be configured). It's possible to leverage the resolution of DIDs not supported by the service by making `GET` requests to `/v1/dids/resolver/{did}`. + + + diff --git a/doc/howto/schema.md b/doc/howto/schema.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/howto/status.md b/doc/howto/status.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/howto/verification.md b/doc/howto/verification.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/service/features.md b/doc/service/features.md new file mode 100644 index 000000000..84849e712 --- /dev/null +++ b/doc/service/features.md @@ -0,0 +1,19 @@ +# Feature List + +- [x] [DID Management](https://www.w3.org/TR/did-core/) + - [x] [did:key](https://w3c-ccg.github.io/did-method-key/) + - [x] [did:web](https://w3c-ccg.github.io/did-method-web/) + - [x] [did:ion](https://identity.foundation/ion/) _Note: updates not yet supported_ + - [x] [did:pkh](https://w3c-ccg.github.io/did-method-pkh/) _Resolution only_ + - [x] [did:peer](https://identity.foundation/peer-did-method-spec/) _Resolution only_ +- [x] [Verifiable Credential Schema](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) Management +- [x] [Verifiable Credential](https://www.w3.org/TR/vc-data-model) Issuance & Verification + - [x] Signing and verification with [JWTs](https://w3c.github.io/vc-jwt/) + - [ ] Signing and verification with [Data Integrity Proofs](https://w3c.github.io/vc-data-integrity/) +- [x] Applying for Verifiable Credentials using [Credential Manifest](https://identity.foundation/credential-manifest/) +- [x] Requesting, Receiving, and the Validation of Verifiable Claims + using [Presentation Exchange](https://identity.foundation/presentation-exchange/) +- [x] Status of Verifiable Credentials using the [Status List 2021](https://w3c-ccg.github.io/vc-status-list-2021/) +- [x] [DID Well Known Configuration](https://identity.foundation/.well-known/resources/did-configuration/) documents +- [ ] Creating and managing Trust documents + using [Trust Establishment](https://identity.foundation/trust-establishment/) \ No newline at end of file diff --git a/doc/VERSIONING.md b/doc/service/versioning.md similarity index 100% rename from doc/VERSIONING.md rename to doc/service/versioning.md diff --git a/doc/VISION.md b/doc/service/vision.md similarity index 100% rename from doc/VISION.md rename to doc/service/vision.md diff --git a/doc/WEBHOOK.md b/doc/service/webhook.md similarity index 100% rename from doc/WEBHOOK.md rename to doc/service/webhook.md diff --git a/sip/README.md b/doc/sip/README.md similarity index 92% rename from sip/README.md rename to doc/sip/README.md index 6f9bbb22e..672324d66 100644 --- a/sip/README.md +++ b/doc/sip/README.md @@ -4,7 +4,7 @@ All feature proposal documents for the SSI Service follow a common format and are known as SSI Improvement Proposals or SIPs. Features must list a DRI (Directly Responsible Individual) and follow the [template here](sips/sip_template.md). -Discussion is encouraged on GitHub issues and pull requests and optionally on our forums. +Discussion is encouraged on GitHub issues and pull requests. ## SIP Status @@ -27,8 +27,9 @@ the [template](sips/sip_template.md), add it to the table below, and open up a p # SIPs + | SIP | Description | DRI | Status | Date of Status | -|------------------------------|---------------------------------------------------|--------------------------------------------------|----------|--------------------| +| ---------------------------- | ------------------------------------------------- | ------------------------------------------------ | -------- | ------------------ | | [SIP-1](sips/sip1/README.md) | SIP Purpose and Guidelines | [Gabe Cohen](https://github.com/decentralgabe) | Accepted | August 24, 2022 | | [SIP-2](sips/sip2/README.md) | Credential Issuance Flow | [Neal Roessler](https://github.com/nitro-neal) | Accepted | September 13, 2022 | | [SIP-3](sips/sip3/README.md) | Key Access: Signing & Verification | [Gabe Cohen](https://github.com/decentralgabe) | Accepted | September 20, 2022 | diff --git a/sip/sip_flow.png b/doc/sip/sip_flow.png similarity index 100% rename from sip/sip_flow.png rename to doc/sip/sip_flow.png diff --git a/sip/sips/sip1/README.md b/doc/sip/sips/sip1/README.md similarity index 100% rename from sip/sips/sip1/README.md rename to doc/sip/sips/sip1/README.md diff --git a/sip/sips/sip2/README.md b/doc/sip/sips/sip2/README.md similarity index 100% rename from sip/sips/sip2/README.md rename to doc/sip/sips/sip2/README.md diff --git a/sip/sips/sip2/assets/application.png b/doc/sip/sips/sip2/assets/application.png similarity index 100% rename from sip/sips/sip2/assets/application.png rename to doc/sip/sips/sip2/assets/application.png diff --git a/sip/sips/sip2/assets/manifest.png b/doc/sip/sips/sip2/assets/manifest.png similarity index 100% rename from sip/sips/sip2/assets/manifest.png rename to doc/sip/sips/sip2/assets/manifest.png diff --git a/sip/sips/sip2/assets/response.png b/doc/sip/sips/sip2/assets/response.png similarity index 100% rename from sip/sips/sip2/assets/response.png rename to doc/sip/sips/sip2/assets/response.png diff --git a/sip/sips/sip2/assets/toplevel.png b/doc/sip/sips/sip2/assets/toplevel.png similarity index 100% rename from sip/sips/sip2/assets/toplevel.png rename to doc/sip/sips/sip2/assets/toplevel.png diff --git a/sip/sips/sip3/README.md b/doc/sip/sips/sip3/README.md similarity index 100% rename from sip/sips/sip3/README.md rename to doc/sip/sips/sip3/README.md diff --git a/sip/sips/sip3/assets/key-access.png b/doc/sip/sips/sip3/assets/key-access.png similarity index 100% rename from sip/sips/sip3/assets/key-access.png rename to doc/sip/sips/sip3/assets/key-access.png diff --git a/sip/sips/sip4/README.md b/doc/sip/sips/sip4/README.md similarity index 100% rename from sip/sips/sip4/README.md rename to doc/sip/sips/sip4/README.md diff --git a/sip/sips/sip4/assets/diagram.png b/doc/sip/sips/sip4/assets/diagram.png similarity index 100% rename from sip/sips/sip4/assets/diagram.png rename to doc/sip/sips/sip4/assets/diagram.png diff --git a/sip/sips/sip4/assets/endpoints.png b/doc/sip/sips/sip4/assets/endpoints.png similarity index 100% rename from sip/sips/sip4/assets/endpoints.png rename to doc/sip/sips/sip4/assets/endpoints.png diff --git a/sip/sips/sip4/assets/manifest.png b/doc/sip/sips/sip4/assets/manifest.png similarity index 100% rename from sip/sips/sip4/assets/manifest.png rename to doc/sip/sips/sip4/assets/manifest.png diff --git a/sip/sips/sip5/README.md b/doc/sip/sips/sip5/README.md similarity index 100% rename from sip/sips/sip5/README.md rename to doc/sip/sips/sip5/README.md diff --git a/sip/sips/sip6/README.md b/doc/sip/sips/sip6/README.md similarity index 100% rename from sip/sips/sip6/README.md rename to doc/sip/sips/sip6/README.md diff --git a/sip/sips/sip7/README.md b/doc/sip/sips/sip7/README.md similarity index 100% rename from sip/sips/sip7/README.md rename to doc/sip/sips/sip7/README.md diff --git a/sip/sips/sip8/README.md b/doc/sip/sips/sip8/README.md similarity index 100% rename from sip/sips/sip8/README.md rename to doc/sip/sips/sip8/README.md diff --git a/sip/sips/sip8/assets/applicationsubmission.png b/doc/sip/sips/sip8/assets/applicationsubmission.png similarity index 100% rename from sip/sips/sip8/assets/applicationsubmission.png rename to doc/sip/sips/sip8/assets/applicationsubmission.png diff --git a/sip/sips/sip9/README.md b/doc/sip/sips/sip9/README.md similarity index 100% rename from sip/sips/sip9/README.md rename to doc/sip/sips/sip9/README.md diff --git a/sip/sips/sip_template.md b/doc/sip/sips/sip_template.md similarity index 100% rename from sip/sips/sip_template.md rename to doc/sip/sips/sip_template.md diff --git a/doc/swagger.yaml b/doc/swagger.yaml index 2bec50baf..9b2d81608 100644 --- a/doc/swagger.yaml +++ b/doc/swagger.yaml @@ -2198,12 +2198,12 @@ info: email: tbd-developer@squareup.com name: TBD url: https://github.com/TBD54566975/ssi-service/issues - description: '{{.Desc}}' + description: 'The Self Sovereign Identity Service: Managing DIDs, Verifiable Credentials, + and more!' license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html title: SSI Service API - version: '{{.SVN}}' paths: /health: get: diff --git a/pkg/server/server.go b/pkg/server/server.go index 2187b36af..adc0cc2d4 100644 --- a/pkg/server/server.go +++ b/pkg/server/server.go @@ -3,14 +3,10 @@ package server import ( - "bytes" - "context" "os" - "text/template" sdkutil "github.com/TBD54566975/ssi-sdk/util" "github.com/gin-gonic/gin" - "github.com/sirupsen/logrus" swaggerfiles "github.com/swaggo/files" ginswagger "github.com/swaggo/gin-swagger" "go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin" @@ -72,23 +68,8 @@ func NewSSIServer(shutdown chan os.Signal, cfg config.SSIServiceConfig) (*SSISer // service-level routers engine.GET(HealthPrefix, router.Health) engine.GET(ReadinessPrefix, router.Readiness(ssi.GetServices())) - - tmpFile, err := writeSwaggerFile(cfg) - if err != nil { - logrus.WithError(err).Warnf("unable to write swagger file, skipping handler") - } else { - httpServer.RegisterPreShutdownHook(func(_ context.Context) error { - logrus.Infof("removing temp file %q", tmpFile.Name()) - err := os.Remove(tmpFile.Name()) - if err != nil { - logrus.WithError(err).Warnf("unable to delete %q during shutdown", tmpFile.Name()) - } - return nil - }) - - engine.StaticFile("swagger.yaml", tmpFile.Name()) - engine.GET(SwaggerPrefix, ginswagger.WrapHandler(swaggerfiles.Handler, ginswagger.URL("/swagger.yaml"))) - } + engine.StaticFile("swagger.yaml", "./doc/swagger.yaml") + engine.GET(SwaggerPrefix, ginswagger.WrapHandler(swaggerfiles.Handler, ginswagger.URL("/swagger.yaml"))) // register all v1 routers v1 := engine.Group(V1Prefix) @@ -130,30 +111,6 @@ func NewSSIServer(shutdown chan os.Signal, cfg config.SSIServiceConfig) (*SSISer }, nil } -func writeSwaggerFile(cfg config.SSIServiceConfig) (*os.File, error) { - t, err := template.ParseFiles("./doc/swagger.yaml") - if err != nil { - return nil, err - } - - var b bytes.Buffer - if err = t.Execute(&b, cfg); err != nil { - return nil, err - } - tmpFile, err := os.CreateTemp("", "swagger.yaml") - if err != nil { - return nil, err - } - - if _, err = tmpFile.Write(b.Bytes()); err != nil { - return nil, err - } - if err := tmpFile.Close(); err != nil { - return nil, err - } - return tmpFile, nil -} - // setUpEngine creates the gin engine and sets up the middleware based on config func setUpEngine(cfg config.ServerConfig, shutdown chan os.Signal) *gin.Engine { gin.ForceConsoleColor()