Skip to content
This repository has been archived by the owner on Dec 12, 2024. It is now read-only.

Commit

Permalink
Update READMEs, docs, add how-tos section, first how-to for DIDs (#607)
Browse files Browse the repository at this point in the history 
* how tos

* table of docs

* consolidate and clean up docs

* remove templating

* did tutorial
  • Loading branch information
@decentralgabe
decentralgabe authored Jul 28, 2023
1 parent b3ad6d1 commit b57a656
Show file tree
Hide file tree
Showing 39 changed files with 316 additions and 179 deletions.
169 changes: 67 additions & 102 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <br />
[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.

Expand All @@ -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`.
Expand Down Expand Up @@ -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 |
Expand Down
3 changes: 1 addition & 2 deletions cmd/ssiservice/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 [email protected]
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @version {{.SVN}}
func main() {
logrus.Info("Starting up...")

Expand Down
19 changes: 0 additions & 19 deletions config/README.md
View file

This file was deleted.

58 changes: 52 additions & 6 deletions doc/README.md
View file
Original file line number Diff line number Diff line change
@@ -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 |


Loading

0 comments on commit b57a656

Please sign in to comment.