vct

README

Verifiable Credential Transparency

The Verifiable Credential Transparency (VCT) is based on certificate transparency RFC6962. The Credentials are included into VCT as append-only Merkle Tree logs. VCT uses the existing Merkle Tree implementation provided by Trillian. VCT was created for the orb project and its usage is described here.

Build and test

To build and test VCT you need:

• Go 1.19 or later
• GNU Make
• Bash
• Docker and Docker-Compose

Run tests:

make unit-test bdd-test

Deploy

VCT itself is a compound of three essential components.

• log-server
• log-signer
• vct

To deploy the service you would need to build them first.

make build-vct build-log-server build-log-signer

1. Run the log-server.

Log server depends on the database. To run DB you can simply use docker-compose for that.

NOTE: We support MySQL and Postgres. If you run your own DB service, do not forget to import schema. See MySQL schema and Postgres schema.

Run Postgres by using docker-compose:

cd ./test/bdd/fixtures/vct && docker-compose up vct.postgres

Then run the log-server.

./build/bin/log-server --pg_conn_str="user=postgres host=localhost password=password dbname=test port=5432 sslmode=disable" --storage_system=postgres -quota_system=noop

Log server will start the RPC server on localhost:8090 and HTTP server on localhost:8091.

Use help flag to find out all available flags ./build/bin/log-server -h.

1. Run the log-signer.

Log signer must be run with the same DB configuration as a log-server. Log signer will start the RPC server on localhost:8090 and HTTP server on localhost:8091. Since those ports are already occupied by the log-server, let's change them.

./build/bin/log-signer --pg_conn_str="user=postgres host=localhost password=password dbname=test port=5432 sslmode=disable" --storage_system=postgres --force_master=true --http_endpoint=0.0.0.0:8099 --rpc_endpoint=0.0.0.0:8098 --quota_system=noop

Use help flag to find out all available flags ./build/bin/log-signer -h.

1. Run the vct.

./build/bin/vct start --logs=maple2021:rw@127.0.0.1:8090

The required argument here is --logs. It specifies an alias for the log, permissions and log-service RPC endpoint. For example, if we want to change logs yearly we can do the following: --logs=maple2020:r@127.0.0.1:8090,maple2021:rw@127.0.0.1:8090

An alias (e.g maple2021) can be any string and it will represent a log-id. When an alias (e.g maple2021) is provided the service will try to get the correlated log-id from the DB, if the record does not exist the service will create a new log-id and it will be assigned to the given alias. The database can be specified by using the --dsn argument.

The vct server by default will be run on localhost:5678.

Use help flag to find out all available flags ./build/bin/vct -h.

Configuration

To get help about startup options use the following command:

$ ./build/bin/vct start -h The output should be similar to this:

Starts verifiable credentials transparency service

Usage:
  vct start [flags]

Flags:
  -a, --api-host string             Host Name:Port. Alternatively, this can be set with the following environment variable: VCT_API_HOST (default ":5678")
      --base-url string             Base URL. e.g (https://vct.com) Alternatively, this can be set with the following environment variable: VCT_BASE_URL
      --database-prefix string      An optional prefix to be used when creating and retrieving underlying databases.  Alternatively, this can be set with the following environment variable: VCT_DATABASE_PREFIX
      --dev-mode string             Enable dev mode. Alternatively, this can be set with the following environment variable: VCT_DEV_MODE
  -d, --dsn string                  Datasource Name with credentials if required. Format must be <driver>:[//]<driver-specific-dsn>. Examples: 'mysql://root:secret@tcp(localhost:3306)/adapter', 'mem://test', 'mongodb://mongodb.example.com:27017'. Supported drivers are [mem, couchdb, mysql, mongodb]. Alternatively, this can be set with the following environment variable: VCT_DSN (default "mem://test")
  -h, --help                        help for start
      --issuers string              Comma-Separated list of supported issuers. Alternatively, this can be set with the following environment variable: VCT_ISSUERS
  -s, --kms-endpoint string         Remote KMS URL. Alternatively, this can be set with the following environment variable: VCT_KMS_ENDPOINT
  -l, --logs string                 Trillian logs comma separated.  Format must be <alias>:<permission>@<endpoint>. Examples: maple2021:rw@server.com,maple2020:r@server.com:9890 Alternatively, this can be set with the following environment variable: VCT_LOGS
      --sync-timeout string         Total time in seconds to resolve config values. Alternatively, this can be set with the following environment variable: VCT_SYNC_TIMEOUT (default "3")
      --timeout string              Total time in seconds to wait until the services are available before giving up. Alternatively, this can be set with the following environment variable: VCT_TIMEOUT (default "0")
      --tls-cacerts string          Comma-Separated list of ca certs path. Alternatively, this can be set with the following environment variable: VCT_TLS_CACERTS
      --tls-serve-cert string       Path to the server certificate to use when serving HTTPS. Alternatively, this can be set with the following environment variable: VCT_TLS_SERVE_CERT
      --tls-serve-key string        Path to the private key to use when serving HTTPS. Alternatively, this can be set with the following environment variable: VCT_TLS_SERVE_KEY
      --tls-systemcertpool string   Use system certificate pool. Possible values [true] [false]. Defaults to false if not set. Alternatively, this can be set with the following environment variable: VCT_TLS_SYSTEMCERTPOOL (default "false")

Each parameter has a description. It should not be hard to start a service. Only one parameter is required to launch a service and requires extra explanation. This is --logs flag. It describes the ledger per tenant.

For example, let's take a look at the following configuration:

e.g --logs=maple2020:rw@127.0.0.1:8090,maple2021:rw@127.0.0.1:8090

It means that we have two tenants (maple2020 and maple2021). Both of them have read/write permissions(rw) and they are using the same Trillian log server (127.0.0.1:8090). You can set permissions to r,w or rw. e.g maple2020:r@127.0.0.1:8090 (only read). Under the hood, the service will create a new log id per tenant and map it to its alias. e.g maple2020 might be mapped to 11715276152711. Where 11715276152711 is created by Trillian. That correlation will be stored in the DB. So, next time when vct service will be up and running we will not create a new log id.

VCT depends on Trillian log server/signer. Deployment should be done similar to trillian deployments.

Databases

VCT Storage

VCT uses Aries generic storage interface for storing data. Backup should be done similarly to other trustbloc projects. In VCT we support the following databases:

• CouchDB
• MySQL
• Memory (backup is not supported)

Use the database-specific command to get all databases and filter them by VCT_DATABASE_PREFIX env.

For instance, to get all databases for CouchDB use the following command:

curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs

Output:

["_replicator","_users","kmspkprimarykey","vctdbmaple2021ldcontexts","vctdbconfig"]

Then, filter databases from the output above by VCT_DATABASE_PREFIX=vctdb env. Databases we need to backup are vctdbmaple2021ldcontexts and vctdbconfig Make a backup according to CouchDB documentation.

Trillian Storage

For Trillian we support the following databases:

• Postgres
• MySQL

Backup should be done according to the official documentation (Postgres or MySQL).

See schemas for better understanding:

• MySQL schema
• Postgres schema.

Note: If you want to restore a backup from the ground up make sure that schema was imported first.

Contributing

Thank you for your interest in contributing. Please see our community contribution guidelines for more information.

License

Apache License, Version 2.0 (Apache-2.0). See the LICENSE file.