Keys and contexts

Every key a VTA holds traces back to one master seed through a predictable derivation tree, and every application gets its own isolated branch of that tree. Understanding the seed and the context model explains both what a VTA can recover from and what stays isolated between applications.

Master seed

Every key a VTA derives comes from a single BIP-32 master seed, generated once when the VTA is set up. Losing the master seed without a backup means losing every key and identity the VTA has ever derived.

• Self-hosted: the master seed is a 24-word BIP-39 mnemonic, generated locally during setup and stored in your OS keyring by default. Back it up securely outside the keyring. Anyone who has it can recreate every key the VTA has ever derived.
• Affinidi-hosted: the master seed is generated inside the Trusted Execution Environment on first boot. Its plaintext never exists outside the enclave’s own memory, not even to Affinidi or to you as the operator. A normal enclave restart is automatic and does not put the seed at risk: the encrypted seed persists outside the enclave, and the next enclave instance decrypts it again as soon as its attestation matches. If the persisted state itself is ever lost, for example when migrating to new infrastructure, an encrypted backup is the only way back, since there is no recovery phrase to write down.

Contexts

A context is a named namespace within a VTA, the VTA’s implementation of the trust context defined by the VTI specification. Each one has:

• Its own BIP-32 base path.
• Its own monotonic key counter.
• Its own access control list.

One VTA can serve many applications without sharing key material across them:

An Admin DID scoped to a context can delegate access within that context to other DIDs by assigning them a role. See Roles and access for what each role can do.

A context can also carry an associated DID of its own, set by an admin with access to that context. This is a label, not a signing identity. It records which DID represents or owns that namespace, for example the DID of an integration provisioned into it. You can look the context up by that DID later, but it plays no part in authentication. See Identity for the DIDs that actually authenticate: the VTA’s own DID, the Administrator DID, and each application’s DID.

How contexts nest

A context can sit at the top level, or under another context as a sub-context. A nested context’s identifier is the full path, so a context created as eng under acme is addressed as acme/eng.

Nesting exists to make authority delegable without handing out the whole VTA. Creating a top-level context is a super-admin operation. Creating a sub-context needs only admin of the parent, or of any ancestor above it, which lets a team own its own branch of the tree and create contexts inside it without being able to touch anybody else’s.

The tree also defines how far a deletion reaches: removing a context removes everything below it. See Manage the contexts on a VTA for what that covers in practice.

What minting a key produces

Minting a key creates a record on the VTA, not a file you receive. The record carries the key’s identifier, its type, the derivation path it was created at, its public key, a status, and an optional label. The private half stays inside the VTA and is what the signing operation uses on your behalf.

A key’s identifier is its derivation path, such as m/26'/2'/2'/0', rather than a short opaque string. Minting is also not idempotent: running the create command twice produces two distinct keys, so list a context’s keys before adding to it if you are trying to avoid duplicates.

Derived keys and internal keys

Most keys are derived: they come from the master seed along a BIP-32 path, so the seed reproduces them and a backup carries everything needed to restore them.

A VTA can also mint an internal key, generated from the system’s random number generator instead of the seed. That difference has consequences worth understanding before you choose one:

• The mnemonic does not recover it, because it was never derived from the seed.
• It is excluded from backups, so a restored VTA comes back without it.
• It is never exported by any surface. The VTA will only ever sign with it.
• It cannot sign did:webvh log entries, precisely because losing it would freeze that DID permanently. It can still be a signing verification method inside a DID document.

An internal key is the right choice when a key must be unable to leave the VTA even under administrative authority. The cost is that losing the VTA’s storage loses the key, and with it the ability to produce any signature that key alone was trusted for. A derived key is the safer default.

Key algorithms

All keys use Ed25519 for signing and X25519 for key agreement. The X25519 key is derived from the Ed25519 private key.

Related