Your private key is the root of trust. TrustDID gives you a clear custody path — from protected files on a laptop to FIPS 140-3 hardware — with a tamper-evident key history and documents that never leave your machines.
Three custody levels — OS file permissions, endpoint-protection (EDR) rules, or a hardware security module. Start simple, escalate as requirements grow; nothing else in the stack changes.
Hardware-backed signing via Crypto4A QxHSM (PKCS#11 or REST), enabling FIPS 140-3 and CCCS certification of the combined stack for federal and high-assurance environments.
Every key rotation is dual-signed, hash-chained, and appended to an auditable log. Rewriting history breaks the chain — and anyone can verify the whole chain independently.
Sealing and checking happen on your machines. Documents are never uploaded — only public facts (identities, vouch lists) and, with an HSM, opaque bytes to sign ever cross the network.
Every TrustDID signature traces back to a private key. If someone gets your private key, they can sign as you. That's why key protection isn't optional—it's the foundation of the entire trust model.
Published in your
DID
document at /.well-known/did.json. Anyone can read it. That's the point—verifiers
use it to confirm your signatures. Treat it like your business card.
Stays on your computer (or HSM). Never shared, never uploaded, never transmitted. Used to create signatures. If it's compromised, rotate immediately and update your DID.
TrustDID provides a clear escalation path. Start simple, increase protection as your needs grow.
Your private keys are stored as .pem files in your
~/.trustdid/keys/ directory. TrustDID automatically restricts file permissions so only your
user account can read them (Unix: 0600, Windows: owner read/write). No extra setup required.
Good for individuals, freelancers, and small teams on single-user machines.
For organizations that need stronger guarantees, your IT or security team can add
an endpoint protection /
EDR
rule to ensure the .trustdid folder is only accessed by the authorized user and TrustDID
software. This integrates with your existing security stack—CrowdStrike, SentinelOne, Microsoft
Defender for Endpoint, or any EDR that supports application-level access policies.
Recommended for multi-user machines, shared workstations, and regulated environments.
The private key lives inside tamper-resistant hardware—it never exists in software memory and can never be extracted. Signing operations happen inside the HSM. Supports FIPS 140-3 certification for federal and high-assurance environments.
For government contractors, financial institutions, and critical infrastructure.
For enterprises requiring the highest level of key protection, TrustDID integrates with network HSMs via PKCS#11 and REST APIs. Signing operations happen inside tamper-resistant hardware—the private key never exists in software memory.
This enables FIPS 140-3 and CCCS certification of the combined TrustDID + HSM stack for federal and high-assurance environments.
Want to evaluate before buying hardware? Crypto4A offers QxEmulator™—a software emulator of the QxHSM that lets you develop and test the full integration without physical hardware. Start in software, move to hardware when ready.
Keys should be rotated periodically, or immediately if a compromise is suspected. TrustDID makes this painless.
did.json file with the new public keydid.json to your websiteOld signatures remain valid. They're timestamped and reference the key ID that was active at signing time. Key history in your DID allows verifiers to look up the correct key for any past signature.
Every rotation is more than a key swap—it's a recorded event. Alongside the
keyHistory in your did.json, each rotation appends an entry to an append-only
sidecar log, did.json.vrfy.log. Every entry is dual-signed (Ed25519 + ML-DSA-44) and
hash-chained to the entry before it, so removing or rewriting history breaks the chain. The rotation
reason is recorded too—scheduled rotation, key compromise, key-loss recovery, policy change, or
initial setup—and anyone can check the whole chain with trustdid-verify --verify-history.
keyHistory—never deleted—so verifiers can always resolve
the key that was active when a document was signed.
did:web identity
resolves through the domain it names. Retention of the key history is ours—but for an
identity on your own domain, continuity of that domain is yours: if the registration lapses or the
DID document stops being served, documents signed under it can no longer be resolved, whatever we
retain. Give the domain the same lifetime as the documents it signs, and put it in your
records-retention policy. Identities hosted on users.trustdid.ca sit on our domain,
which we keep alive.
SHA-256 hash comparison detects any modification—even a single byte change breaks the verification.
Dual-proof manifest structure means attackers cannot create valid .vrfy files without the private key.
DID resolution verifies the signer's identity against their own domain. DNS records add a second anchor.
ML-DSA-44 post-quantum signatures are included by default. Documents signed today remain safe against future quantum attacks.
Verification uses the signer's published DID, fetched directly from their domain over HTTPS. No intermediary to intercept.
Key rotation updates your DID. HSM integration prevents key extraction. Trust registry can revoke compromised signers.
Even without a suspected compromise, regular rotation limits the blast radius of an undetected breach.
Not by email, not by Slack, not by USB drive. Each person or department should have their own key pair.
Keep an encrypted backup of your private key in a separate, secure location. If your primary key store fails, you can restore.
Periodically verify that your published did.json matches
what you expect. Unauthorized changes mean a compromise.
If your signatures have legal or financial weight, hardware-backed key storage eliminates the risk of software-based key extraction.
This section is for architects, security engineers, and anyone who wants to understand exactly how TrustDID integrates with the Crypto4A QxHSM at the protocol level. If you're evaluating TrustDID for a high-assurance environment, this is for you.
TrustDID's signing engine is designed with a clean separation: it assembles the .vrfy
manifest and handles all document processing, but delegates the actual cryptographic signing operation to a
pluggable backend. Today that backend reads a local .pem file. With
HSM
integration, the backend calls the QxHSM instead—everything else stays the same.
The industry-standard
HSM
interface. TrustDID calls C_SignInit() + C_Sign() with the pre-computed
SHA-256 hash.
The QxHSM returns the signature bytes. The private key never leaves the hardware boundary.
Crypto4A's PKCS#11 NG variant supports ML-DSA natively (since QxHSM 4.4 / QxOS 5), so both Ed25519 and ML-DSA-44 signing can happen inside the HSM.
Best for: on-premises deployments, existing PKI infrastructure, direct hardware access.
For network and cloud-based QxHSM access. TrustDID sends the hash over TLS to the QxHSM's REST endpoint, authenticated with a client certificate or API token. The HSM signs and returns the result.
Configuration: C4A_PKCS11_HSM_CLIENT=rest + key manager address
and port.
Best for: cloud deployments, remote signing, multi-site architectures.
SHA-256 hash of the original document is computed locally on the user's machine. The document never leaves the local environment—only the 32-byte hash moves forward.
TrustDID constructs the JSON payload (DID, hash, timestamp, filename, metadata) and canonicalizes it with sorted keys and compact separators. This canonical form is what gets signed.
The canonical payload bytes are sent to the QxHSM via PKCS#11 or REST. The HSM signs with the Ed25519 private key stored in its secure enclave. The signature bytes are returned to TrustDID.
C_SignInit(session, CKM_EDDSA, key_handle)
C_Sign(session, payload_bytes) → signature_bytesTrustDID wraps the payload + returned signature into the full manifest structure (version, type, DID, payload, proof). This manifest is then canonicalized for the second signature.
The full manifest bytes are sent back to the QxHSM for a second Ed25519 signature. This dual-proof structure prevents tampering with the .vrfy file itself.
The same manifest bytes are signed a third time with ML-DSA-44 (NIST FIPS 204) using the post-quantum key stored in the QxHSM. QxOS 5 supports ML-DSA natively via PKCS#11 NG.
Result: three signatures, all created inside hardware, private keys never in software memory.
TrustDID assembles the final .vrfy file with all three proofs and writes it alongside the original document. The document is untouched. The signing operation is complete.
✓ Document (never leaves)
✓ SHA-256 hash computation
✓ Manifest assembly & canonicalization
✓ .vrfy file generation
✓ DID consistency check
🔒 Ed25519 private key (permanent resident)
🔒 ML-DSA-44 private key (permanent resident)
✓ Ed25519 document proof signature
✓ Ed25519 manifest proof signature
✓ ML-DSA-44 post-quantum proof signature
Access to signing keys in the QxHSM is controlled through multiple layers:
For TrustDID's managed service, an API token scoped to the customer's key slot provides the authentication. For on-premises deployments, the organization controls the full PKCS#11 session lifecycle.
Every verification answers two independent questions: is it genuine?—the cryptography, identical for every verifier—and who vouches for the signer?—your trust anchors and registries. The math tells you it's genuine—people tell you whether to trust it. That second axis is where trust registries come in.