Usage

Create a first identity

The tsp command line tool will store its state using the Aries-Askar interface in a SQLite file in the current directory.

To create a test did:web identity run the following command:

tsp create example

Output:

INFO tsp: created new database
INFO tsp: created identity did:web:tsp-test.org:user:example

We can add an alias to a VID using the --alias argument:

tsp create example --alias example

In subsequent commands we can type example instead of did:web:tsp-test.org:user:example.

Every tsp subcommand also supports the --verbose or -v flag for a more verbose output:

tsp --verbose create example

Output:

TRACE tsp: opened database database.sqlite
 INFO tsp: added alias example -> did:web:tsp-test.org:user:example
 INFO tsp: created identity did:web:tsp-test.org:user:example
TRACE tsp: published DID document to https://tsp-test.org/user/example/did.json
TRACE tsp: persisted database to database.sqlite

Resolve a VID

VIDs created with the tsp tool are published on tsp-test.org. Currently Rust TSP is able to verify did:web and did:peer VIDs

To resolve and verify a VID, run the following:

tsp verify did:web:tsp-test.org:user:example

Output:

 INFO tsp: did:web:tsp-test.org:user:example is verified and added to the database

The verify command also support the alias argument:

tsp verify did:web:tsp-test.org:user:example --alias example

Send a message

For this example we will create two databases and identities - alice and bob.

You could perform the operations for alice and bob on different computers, for this example we will seperate them by using distinct databases.

Use the --database flag to specify the file name of the database.

First create the identity for alice:

tsp --database alice create alice --alias alice

Then create the identity for bob:

tsp --database bob create bob --alias bob

Let alice verify bob's VID and add it to the database alice:

tsp --database alice verify did:web:tsp-test.org:user:bob --alias bob

Let bob verify alice's VID and add it to the database bob:

tsp --database bob verify did:web:tsp-test.org:user:alice --alias alice

Let bob start listening for a message:

tsp --database bob receive --one bob

The --one argument makes the command exit when the first message is received.

Since the above command will block / wait for a first message we should use a new / different terminal to send the message from alice.

To send a message run the following:

echo "Hello Bob!" | tsp --database alice send --sender-vid alice --receiver-vid bob

Note that alice and bob are aliases of did:web:tsp-test.org:user:alice and did:web:tsp-test.org:user:bob.

We can also use aliases for the argument, for example:

echo "Hello Bob!" | tsp -d alice send -s alice -r bob

In the other terminal window the message should appear:

tsp --database bob receive --one bob

 INFO tsp: listening for messages...
 INFO tsp: received message (11 bytes) from did:web:tsp-test.org:user:alice
Hello Bob!

DID types supported

The TSP CLI example application supports two types of decentralized identifiers:

• did:web, created using tsp create. These are resolved by finding a .json file on a server and checking its contents.
• did:peer, created using tsp create-peer. These are essentially self-signed identifiers.

The TSP CLI can use two types of transport:

• https, which forces the use of a broadcast server application (see demo-server.rs), but will work well across firewalls.

• tcp, which requires a direct network connection between two instances of the TSP CLI. In practice you can use this only on a local network (or the same machine, if you use different ports), but this functionality is added to demonstrate the flexibility of having multiple transports. This transport mode is only available to did:peer. To use TCP transport, use the --tcp address:port flag to tcp create-peer.

Pretty print messages

The send command supports the --pretty-print argument. This wil output the CESR-encoded TSP mesage that is sent.

Continuing with the alice and bob example:

echo "Hello Bob!" | tsp --pretty-print -d alicen send -s alice -r bob

Output:

 INFO tsp::async_store: sending message to https://tsp-test.org/user/bob
CESR-encoded message:
-EABXAAA9VIDAAALAAAZGlkOndlYjp0c3AtdGVzdC5vcmc6dXNlcjphbGljZQ8VIDAAAKAAZGlkOndlYjp0c3AtdGVzdC5vcmc6dXNlcjpib2I4CAX7ngr3YHl2z91L-anFBYxbQhM48CT_wqrCCRNdsN5fm-oshqvwqnKDK5rLkn_kvVI8aWZ7SEhiaiB8N6e-bjInrBbhNII0BAceo-mZoSvG3MY_UEqrgzP4kpeLJJK9MdQx53c4nxKh6_jvB2DuXJ6TBNjj-lXszyTH8yDAMSioDRluucSBpPAg
 INFO tsp: sent message (11 bytes) from did:web:tsp-test.org:user:alice to did:web:tsp-test.org:user:bob

In a terminal window supporting colors this will look like the following:

-EABXAAA9VIDAAALAAAZGlkOndlYjp0c3AtdGVzdC5vcmc6dXNlcjphbGljZQ8VIDAAAKAAZGlkOndlYjp0c3AtdGVzdC5vcmc6dXNlcjpib2I4CAX5I7ozAGaFVqTxz8PJve0Tscor80fvds6hCf3yDUtOnHpXZ84uXFGXM-PcfLDWsRWvH7SoOG4UwQU8H-zEfBFs0skhjtk0BAtrMgdWXM9Mfdgiq2awx6VAWCUUYCfjv1tdQqnjNc4eB-IOdBVA459uAFX2EGfdWWGp2OxxwbAutneudE9zYUBg

The first red part is the TSP prefix. The purple part is the sender VID, the blue part the receiver VID, the yellow is the ciphertext and the cyan part is the signature.

The bold characters note the CESR selector of the part.