The complete user guide.

Contents

1. Setup — Create Your Identity
2. What a Verification Reports
3. Trusting Registries
4. Sign & Deploy the DID Document Business
5. DNS Records (Optional DNSSEC) Business
6. Add Department Keys Business
7. Add Personal Keys Business
8. Members & Shared Profiles Business
9. Signing Documents
10. Verifying Documents
11. Encrypting & Decrypting
12. Batch Signing a Directory
13. Windows Service & Email Plugins
14. Browser Plugin
15. Testing Your Deployment
16. Maintenance & Key Rotation
17. Your DID — How It Works Professional
18. Removing Your Profile Professional
19. Command Reference

Setup — Create Your Identity

trustdid-setup --managed YOUR_TOKEN YOUR_ID

# Managed mode (after web enrollment)
trustdid-setup --managed YOUR_TOKEN YOUR_ID

# Self-managed mode (interactive)
trustdid-setup business --self-managed

The installer will prompt for:

• Domain name — your company domain (e.g. trustdid.ca)
• Full name — IT contact name
• Email address — IT contact email
• Organisation name — optional
• DNSSEC — whether to embed a self-sovereign DNS anchor (see Step 3)
• Trust Registry — optionally publish your claimed registry affiliation in your own did.json (subject-asserted; see Trusting Registries)

On completion, the following files are created:

~/.trustdid/
  config.json              ← signing configuration
  did.json                 ← DID document (deploy this)
  dns_records.txt          ← TLSA records (if DNSSEC enabled)
  keys/
    active/
      signing.pem          ← Ed25519 private key (keep secret!)
      signing.pub          ← Ed25519 public key
      encryption.pem       ← X25519 private key (keep secret!)
      encryption.pub       ← X25519 public key
      signing_pq.pem       ← ML-DSA-44 secret key (keep secret!)
      signing_pq.pub       ← ML-DSA-44 public key
    backup/
      trustdid_backup_*.tar.gz

What a Verification Reports

Every TrustDID verification answers two independent questions. Document authenticity — is it genuine? — is objective and identical for every verifier: Verified / Inconsistent / Failed / Unsigned. Trusted signer — who vouches for it? — is answered relative to the trust registries you rely on: Yes / No / Unknown. The math tells you it's genuine — people tell you whether to trust it.

TrustDID Document Verification
==============================
  Signer:    did:web:acme.ca#active
  Timestamp: 2026-08-12T14:03:22Z

  Document authenticity   Verified
  Trusted signer          Yes
    Authentic and trusted

Verifying without a network

Verification normally fetches the signer’s DID document and asks your trust registries live. When neither can be reached, TrustDID falls back to copies it stored on an earlier run, kept under ~/.trustdid/cache/, so a laptop offline for a weekend still gets an answer instead of “could not resolve”.

A cached answer never passes itself off as a live one. The headline says so, and the report names every source it fell back to and how old the copy is:

  Document authenticity   Verified (from cache)
  Trusted signer          Yes

  Offline: some checks used stored copies, not live sources.
    - DID document: cached copy, 14h ago
    A key revoked, or a registry entry withdrawn, after those were
    stored would not be visible here. Re-run with a network
    connection before relying on this for anything consequential.

Stored copies are usable for 72 hours. Past that they are ignored entirely and verification reports that it could not check — beyond a few days an unnoticed revocation is too likely for a snapshot to be worth trusting. Set TRUSTDID_CACHE_MAX_AGE to change the window (any duration, e.g. 24h); zero or a negative value disables cached reads altogether, so verification always requires a live source.

Trusting Registries

The "Trusted signer" answer comes from the trust registries your verifier consults — a registry vouches for the signers it lists. You decide which registries to rely on:

# Add a registry your verifier will consult (interactive)
trustdid-setup --add-trusted-registry

# List the registries you currently rely on
trustdid-setup --list-trusted-registries

# Stop relying on a registry
trustdid-setup --remove-trusted-registry DID

Provisioning asks this too: trustdid-setup --managed and business --self-managed end with "Add a trust registry your verifier should trust?" and run the same prompts. The interactive flow resolves the registry's DID, probes its TRQP v2.0 endpoint, and writes the entry to trustRegistries in your local ~/.trustdid/config.json. After adding one, run trustdid-check: it re-validates all configured registries — resolves each registry DID, probes TRQP v2.0, and reports public/private/token status.

In a business, set the list once. The admin lists the registries on the dashboard's Trusted registries page and every member's machine inherits it on the next sync — see Members & Shared Profiles. The commands above are for a Professional identity, a self-managed installation, or a registry only this machine should trust.

Sign & Deploy the DID Document

Sign the DID document to produce a verification manifest (did.json.vrfy), then deploy both files to the web server.

# Sign the DID document
trustdid-sign ~/.trustdid/did.json

This generates did.json.vrfy alongside did.json. Deploy both to your web server:

https://trustdid.ca/.well-known/did.json
https://trustdid.ca/.well-known/did.json.vrfy

DNS Records — DNSSEC Anchoring

If you enabled DNSSEC during setup, the installer generated a dns_records.txt file. Add these DNS records to anchor your DID public key in the DNS system:

_did.trustdid.ca. IN URI  1 0 "did:web:trustdid.ca"
_did.trustdid.ca. IN TLSA 3 1 0 302a300506032b65700321...

These records strengthen the binding between your signing key and your domain. Without them, the key is merely declared by your DID document; with matching _did URI and TLSA records under your domain, verifiers report the binding as corroborated by DNS — and DNSSEC-signing those records is designed to let verifiers validate that corroboration cryptographically. Stronger binding makes impersonating your domain harder. It says nothing about trust: whether you are a trusted signer is answered by the registries that vouch for you.

If DNSSEC was not live when you first ran setup, you can embed the anchor later:

trustdid-setup --update-dnssec

Regenerate DNS Records

After key rotation or domain changes, regenerate the URI and TLSA DNS records from your existing configuration:

trustdid-setup --dnsrecords

This reads your current config.json and did.json, and outputs fresh DNS records to dns_records.txt. No keys are modified.

Add Department Keys

Each department can have its own signing key. Use the --profile subcommand to add department or personal keys to an existing business config.

trustdid-setup business --profile

The installer detects the existing DID and prompts:

  Found existing DID document with 3 key(s): active, active-encrypt, active-pq
  Org key (#active) found. DNSSEC and Trust Registry
  already configured by IT - no changes needed.

  Key purpose:
    [1] Department key  (e.g. finance, hr, sales, legal)
    [2] Personal key    (nickname or auto-generated ID)

  Select (1/2): 1
  Department name (one word, lowercase letters/digits): finance
  Key ID: #finance

The updated did.json now contains both the org key and the department key. The IT admin must:

1. Collect the updated did.json from the employee
2. Re-sign it: trustdid-sign did.json
3. Re-deploy both did.json and did.json.vrfy to the web server

Add Personal Keys

Personal keys work the same way as department keys, but are tied to an individual rather than a department. Select option [2] Personal key during setup.

  Key purpose:
    [1] Department key
    [2] Personal key

  Select (1/2): 2

  Personal key identifier:
    [1] Nickname  (e.g. alice, laptop, home)
    [2] Short UUID (auto-generated)

  Select (1/2): 1
  Nickname: alice
  Key ID: #alice

The same re-deploy workflow applies: IT collects the updated DID document, re-signs, and re-deploys.

Members & Shared Profiles

A business is more than one laptop. From the dashboard, the admin invites the people of the organisation; each of them gets their own identity did:web:<your-domain>:public:<label> and their own token, and their keys are generated on their own machine and never leave it. Role identities such as #finance are shared profiles: created once by the admin, handed to chosen members encrypted with each person's own key, and installed automatically by the service on their machines.

Add members

Sign in to the dashboard and open Members. Add a person by email, or import a CSV (email, name, label, visibility) and confirm the preview. Each member is private (an opaque 8-character label) or public (a readable label you choose). Either way only the identity document is published; no list of members or email addresses is served. The seat count follows your licence.

The member receives an invite email with one command, also shown once on the page. It works once and expires in 7 days — treat it like a password-reset link.

An address outside your domain is accepted after a confirmation. From the same page you can resend an invite that expired, suspend a member (their token stops working and their machine learns it on the next sync; signing as them is refused until you reactivate), or remove them (see Day to day). The page shows each member's last sync, so you can see whose service is not running.

Join from your own machine

On the member's machine, install the software bundle and run the command from the invite:

trustdid-setup --managed <INVITE> <BUSINESS-ID>

This generates the member's Ed25519, X25519 and ML-DSA-44 keys locally, publishes their identity document, exchanges the invite for their personal token, and pulls the organisation's licence. From then on:

trustdid-sign <document>        # signs as the member
trustdid-setup --sync            # ask the business what is new (the service does this every 15 minutes)
trustdid-setup --sync --force    # same, ignoring the cached answer
trustdid-check                   # shows the member, the last sync, and installed shared profiles

Running the invite command a second time on the same machine does nothing and says so. Enrolling the same account on a second machine is refused, because the keys published for that identity live on the first one; to move to a new machine, ask your admin for a fresh invite (which retires the old identity) or, for a Professional identity, rotate the keys from the new machine with --replace-keys after restoring your backup.

More than one account on a machine

Each TrustDID account you enrol on a machine — a Professional identity, a business held as its administrator, a business joined as a member — is an identity in config.json, with its own token and licence. Enrolling a second one adds it beside the first. The profile you sign with decides which identity's licence and credential are used; the active profile is the default.

trustdid-setup --identities      # what this machine holds, and which profiles sign under each
trustdid-setup --active jackvid  # sign as this profile (and its identity) by default
trustdid-setup --remove-identity acme.ca   # forget an account no profile uses any more

Shared profiles

On the dashboard's Shared profiles page, create a profile (for example finance), list the email addresses that sign as it, and tick the members who should hold it. The page shows a one-time command; run it on the admin's machine:

trustdid-setup business --shared-profile finance --action-token <TOKEN>

That machine generates the profile's keys, publishes its document, signs the key bundle with the admin's own identity, encrypts one copy per holder to that person's published key, and uploads only the ciphertext. TrustDID never sees the private keys. Each holder's service installs the profile on its next poll after verifying the signature and checking the keys against the published document. Holders can then sign as it:

trustdid-sign --profile finance invoice.pdf

Day to day

• Add or remove a holder in the matrix and Save holders. New holders need a bundle: the page mints the re-grant command, run it on the machine that holds the profile. Removed holders' machines delete it on their next sync (a backup is kept).
• Rotate keys when a holder leaves. Every holder receives the new version; the old keys move to keyHistory.
• Retire ends the profile; its document stays published, deactivated, so old signatures keep verifying. Reactivate brings it back under the same identity with new keys.
• Removing a member revokes their token and retires their document; the dashboard then lists the shared profiles they held so you can rotate them.
• Trusted registries are set once on the dashboard's Trusted registries page. If your plan provisioned a registry for you, one click (Trust it) lists it with its query token copied for you; for any other registry enter its DID and, if it is private, its trq_ query token from the registry owner. Every member's service installs the list on its next sync, marked managed by the business; a registry you disable or remove disappears from their machines the same way. Members cannot edit those entries (--add-trusted-registry refuses them and points here), and anything they added themselves stays theirs.

Signing Documents

Sign any file type — PDF, DOCX, images, spreadsheets, anything:

# Basic signing (uses active profile)
trustdid-sign contract.pdf

# With metadata
trustdid-sign invoice.pdf --reason "Monthly invoice" --location "Ottawa, ON"

# Using a specific profile
trustdid-sign report.pdf --profile finance

# TUI mode (animated terminal UI)
trustdid-sign report.pdf --tui

Re-signing a file that already has a .vrfy asks what to do. Say so up front with --if-exists — ask, replace or keep. In a script or any non-interactive run there is nobody to ask, so the existing manifest is replaced:

# Never prompt; overwrite the old manifest
trustdid-sign contract.pdf --if-exists replace

# Never prompt; leave an existing manifest untouched
trustdid-sign contract.pdf --if-exists keep

This produces a .vrfy file alongside the original:

contract.pdf          ← original document (unchanged)
contract.pdf.vrfy     ← verification manifest (send both)

The .vrfy file contains:

• SHA-256 hash of the document
• Ed25519 signature (proof of authorship)
• ML-DSA-44 post-quantum signature (quantum-safe)
• Timestamp, filename, file size, MIME type
• DID and key ID of the signer

Verifying Documents

Verify a signed document — all verification happens locally on your computer:

# Basic verification
trustdid-verify contract.pdf

# The .vrfy file is auto-detected (contract.pdf.vrfy)
# Or specify it explicitly:
trustdid-verify contract.pdf contract.pdf.vrfy

# TUI mode (animated terminal UI)
trustdid-verify contract.pdf --tui

# Output result as JSON (for scripting)
trustdid-verify contract.pdf --json

# Skip document hash check (email body verification)
trustdid-verify contract.pdf --skip-hash

The verifier checks:

1. Cryptographic integrity — document hash matches signature
2. DID resolution — fetches the signer's public key from their website
3. DNS anchoring — verifies TLSA record (if DNSSEC enabled)
4. Trusted signer — asks the trust registries you rely on whether they vouch for the signer (see Trusting Registries)
5. Post-quantum signature — verifies ML-DSA-44 proof

The result reports the two axes separately: Document authenticity (Verified / Inconsistent / Failed / Unsigned) and Trusted signer (Yes / No / Unknown). For scripting, trustdid-verify exits 1 only when authenticity fails — "Trusted signer: No" still exits 0.

Encrypting & Decrypting

Encrypt a document for a specific recipient using their public encryption key:

# Encrypt for a recipient
trustdid-encrypt confidential.pdf alice@trustdid.ca

# Specify which key to use (skip interactive menu)
trustdid-encrypt report.pdf bob@example.com --key finance-encrypt

# TUI mode (animated terminal UI)
trustdid-encrypt --tui

This produces two files to send to the recipient:

confidential.pdf.enc   ← encrypted data
confidential.pdf.meta  ← encryption metadata

The recipient decrypts with their private key:

# Auto-detect profile from .meta
trustdid-decrypt confidential.pdf.enc

# Specify profile manually
trustdid-decrypt confidential.pdf.enc --profile finance

# TUI mode (animated terminal UI)
trustdid-decrypt --tui

Batch Signing a Directory

Sign all files in a directory at once — ideal for website content, document libraries, or release packages:

# Sign all files in a directory
trustdid-sign-dir /var/www/html --profile active --reason "Release v2.1"

# Recursive (include subdirectories)
trustdid-sign-dir ./content --recursive --profile finance

# Dry run (list files without signing)
trustdid-sign-dir ./site --recursive --dry-run

# Exclude specific extensions
trustdid-sign-dir ./site --recursive --exclude .log --exclude .tmp

The script automatically skips: .vrfy, .meta, .enc, .pem, .pub, .key, .pyc files, and directories like .git, node_modules, __pycache__.

Windows Service & Email Plugins

On a member's machine the service is also the sync agent. Every 15 minutes it asks the business what has changed for this member and installs shared profiles and trusted registries, pulls a renewed licence, and notes a suspension. POST /sync on the API port runs a pass now; /health reports the last sync under member. A machine without the service does the same with trustdid-setup --sync.

The TrustDID service runs a local REST API (port 8080) and a static file server (port 8000) that power the Outlook and Thunderbird plugins for email signing and verification.

Install & Start (Windows)

# Install as Windows service (requires admin)
trustdid-service install

# Start the service
trustdid-service start

# Stop the service
trustdid-service stop

# Check whether it is running
trustdid-service status

# Uninstall
trustdid-service uninstall

Run Standalone (Any Platform)

# Run in foreground (all platforms)
trustdid-service run

# Custom ports
trustdid-service run --api-port 8443 --static-port 8444

# Print systemd unit template (Linux)
trustdid-service --systemd

Once the service is running, install the Outlook add-in manifest or the Thunderbird .xpi extension to enable automatic email signing and one-click verification.

Verify Your Deployment

After setup, use the built-in test tools to confirm everything is working correctly:

# Test local environment (keys, config, DID document)
trustdid-test-local

# Test remote resolution (fetches your DID from the web, verifies signatures)
trustdid-test-remote

trustdid-test-local validates your local ~/.trustdid environment: config structure, key files, DID document consistency, and profile mappings — all without network access.

trustdid-test-remote performs an end-to-end test: resolves your DID from your published domain, fetches the public keys, and verifies that your local keys match what's published. This confirms that verification will succeed for anyone on the internet.

Install the Browser Plugin

The TrustDID browser extension for Chrome, Edge, and Firefox lets you verify signed web pages and documents, and sign emails in Gmail directly from your browser.

Chrome / Edge

1. Open Chrome or Edge and navigate to chrome://extensions/ (or edge://extensions/)
2. Enable Developer mode (toggle in the top-right corner)
3. Click Load unpacked
4. Select the extracted chrome-edge/ folder from the downloads page
5. The TrustDID icon appears in your browser toolbar

Firefox

1. Open Firefox and navigate to about:debugging#/runtime/this-firefox
2. Click Load Temporary Add-on...
3. Select manifest.json from the extracted firefox/ folder
4. The TrustDID icon appears in your browser toolbar
5. For permanent install: about:addons > gear > Install Add-on From File

When you visit a page that has a .vrfy file, the icon turns blue. Click it to verify — it turns green when the signature is valid. In Gmail, the extension adds sign and verify buttons directly in the compose and read views.

Your DID — How It Works

Your TrustDID email identity creates a DID that looks like this:

did:web:users.trustdid.ca:user:52ab2c63

This resolves to a publicly accessible DID document at:

https://users.trustdid.ca/user/52ab2c63/did.json

Share your DID with anyone who needs to verify your documents or send you encrypted files.

Removing Your Profile

To remove your email identity and delete the remote DID document from users.trustdid.ca:

# Remove by email address (uses stored token)
trustdid-setup --remove you@example.com

# Remove by UUID
trustdid-setup --remove 52ab2c63

The removal process:

1. Deletes the remote registration and DID document from users.trustdid.ca
2. Removes the profile from local config.json
3. Cleans up local DID document and email mappings