Deep Dive: ksp-types¶
Overview¶
crates/ksp-types holds the identifiers, encodings, domain strings and
evidence structures that subsystems must agree on byte for byte. Its own
module docs say it has "no behaviour, no policy and no I/O".
It is the bottom of the dependency pyramid: nothing internal depends on it, and it depends on nothing internal.
Responsibilities¶
- Define the identifiers: vaults, principals, agents, actors, secrets, versions and levels.
- Define the canonical encoding helpers, and the rule that keeps maps out of anything signed.
- Define the signature and HPKE domain strings.
- Define the evidence structures: intent, report, observation, audit record.
- Define the two capability vocabularies, and keep them apart.
- Provide the Shamir implementation over GF(2^8).
Architecture¶
graph TB
META["metadata.rs<br/>identifiers, levels, BoundMetadata"]
CBOR["cbor.rs<br/>the canonical encoding helpers"]
DOM["domains.rs<br/>the domain strings"]
EVID["evidence.rs<br/>intent, report, observation, audit record"]
CAP["capability.rs<br/>the lease capability"]
CAPCFG["capability_config.rs<br/>the host capability vocabulary"]
KEY["content_key.rs<br/>the 32-byte AEAD key"]
SHAMIR["shamir.rs<br/>GF(2^8) secret sharing"]
META ~~~ CBOR
CBOR ~~~ DOM
DOM ~~~ EVID
EVID ~~~ CAP
CAP ~~~ CAPCFG
CAPCFG ~~~ KEY
KEY ~~~ SHAMIR
Identifiers¶
| Identifier | Shape | Notes |
|---|---|---|
VaultId |
opaque | Names the vault |
PrincipalId |
a strict UUID | parse checks length, hyphen positions, lowercase hex, the v4 version nibble and the RFC 4122 variant nibble |
AgentId |
a PrincipalId |
The agent's own UUID |
ActorId |
enum | User, Agent, Admin; prints as user:, agent: or admin: |
OpaqueSecretId |
opaque | The secret's name in the store, and nothing else |
RecordVersion |
a number | One version of one secret |
Level |
enum | Admin, User, Agent(AgentId); parse refuses an agent- level that is not a UUID |
PrincipalId is strict¶
PrincipalId::parse checks:
- the exact length,
- the hyphen positions,
- lowercase hex only,
- the v4 version nibble,
- the RFC 4122 variant nibble.
This is deliberate. A principal UUID appears in a path, and a path is
security-relevant. The strictness is what makes p/<vault>/<principal>/...
unambiguous.
Level::parse refuses a non-UUID agent level¶
agent-<non-uuid> is refused. A level that could be spelled two ways would
be a level two readers could disagree about.
The actor prefix¶
ActorId's Display is user:, agent: or admin:. The prefix is what
makes an actor's role visible in a signed record, and what stops a user
actor from being read as an admin one.
Levels are siblings¶
flowchart LR
ADM["admin"] -->|"a copy may be made"| USR["user"]
USR -->|"a copy may be made"| AGT["agent-<id>"]
AGT -.->|"never copied back"| USR
AGT -.->|"never copied back"| ADM
Sharing is one-way. An agent-<id> record is never copied back up to
user or admin. The arrow that would allow it is drawn dashed because it
does not exist.
The Canonical Encoding¶
This is the crate's most consequential rule.
flowchart TD
A["a structure to sign or hash"] --> B{"is it a map?"}
B -->|"yes"| C["REFUSED<br/>maps are forbidden in<br/>signed structures"]
B -->|"no"| D["a fixed-order Rust struct<br/>or an explicit CBOR array"]
D --> E["ciborium encodes it"]
E --> F["the bytes that get signed"]
The reason is in cbor.rs:
ciboriumis not RFC 8949 ยง4.2.1 canonical CBOR. The hazard is removed structurally: every signed structure is a fixed-order Ruststructor an explicit CBOR array. Maps are forbidden for signed structures.
A map's key order would change the bytes a signature covers. A fixed-order struct or an explicit array cannot.
Two more rules from the same file:
- An encoder change that widened integers would silently change every signature. The types are chosen so the widths are pinned.
decode_valueis only for a reader that must show a record it cannot type - the audit view. Nothing re-encodes the result.
Domain Strings¶
Thirteen domains, each ending in -v1, asserted distinct by a test.
graph LR
subgraph Signing["Signature domains"]
DE["DOMAIN_ENROLMENT"]
DP["DOMAIN_POLICY"]
DT["DOMAIN_TOKEN"]
DPO["DOMAIN_POP"]
DI["DOMAIN_DELETE_INTENT"]
DR["DOMAIN_DELETE_REPORT"]
DA["DOMAIN_ABSENCE_OBSERVATION"]
DAR["DOMAIN_AUDIT_RECORD"]
DSA["DOMAIN_SWEEPER_ARMING"]
DSP["DOMAIN_SWEEP_PROOF"]
DV["DOMAIN_VAULT_AAD"]
DF["FINGERPRINT_DOMAIN"]
end
subgraph Hpke["HPKE info strings"]
HR["HPKE_INFO_RECORD<br/>keyspout-record-v1"]
HD["HPKE_INFO_DELIVERY<br/>keyspout-delivery-v1"]
end
Two of these carry a specific weight:
DOMAIN_AUDIT_RECORDis separate fromDOMAIN_DELETE_REPORT, so an audit record can never verify as a deletion report.- The two HPKE
infostrings separate the record envelope from the delivery envelope. The same key pair used for both would otherwise open the other.
The Two Capability Vocabularies¶
| Type | Variants | What it describes |
|---|---|---|
LeaseCapability |
None, NativeExpiry, Scheduled { interval } |
What a store can do about expiry |
HostCapability |
PathConfinement, MemoryBarrier |
What a machine can enforce |
GuaranteeLevel |
Full, Weakened, None |
How much of a capability was established |
AdmissionDecision |
- | Whether a lease is admitted |
AdmissionRefusal |
- | Why it is not |
GuaranteeLevel is ordered Full > Weakened > None, and None means no
mechanism, not a weaker form of one.
GuaranteeLevel is ordered Full > Weakened > None. None means no
mechanism, not a weaker form of one.
The admission rule¶
flowchart TD
L["LeaseCapability"] --> N{"the capability"}
N -->|"None"| N1["admits nothing"]
N -->|"NativeExpiry"| N2["admits any duration"]
N -->|"Scheduled { interval }"| N3["admits D >= 2 x interval"]
The 2 x interval floor is computed with checked_mul, so an absurd
interval refuses rather than wrapping into a small number that would
admit everything.
Two vocabularies, never mixed¶
capability_config.rs opens with the sentence:
Host capability is not lease capability.
They live in separate modules, with separate types, and they never meet. A store's ability to expire a record says nothing about whether the machine can confine a process.
The Evidence Structures¶
evidence.rs defines the shapes that more than one subsystem must agree on.
| Structure | Fields | What it says |
|---|---|---|
DeletionIntent |
record, deadline, authorized_deleters |
What may be deleted, by when, and by whom |
DeletionReport |
record, actor, reported_deleted_at |
What an actor says it did |
AbsenceObservation |
record, observed_at, state |
What somebody saw was not there |
AuditRecord |
operation, target, actor, outcome |
What happened, to what, by whom |
Every one of them carries the record's identity, and none of them carries a key.
DeletionReport.reported_deleted_at is documented in the code as "the
actor's claim about the deletion time. Not evidence of erasure". The
wording is deliberate, because the field is exactly where a reader would
otherwise over-read the guarantee.
The Content Key¶
ContentKey is a 32-byte AEAD key with zeroize on drop.
Its erasure hooks are available only under the test-observer feature or
in tests:
The
test-observerfeature retains a copy of the key bytes in a thread-local. It must never be enabled in a shipped build.
That feature is enabled as a dev-dependency of ksp-record and
ksp-deletion, and nowhere else. It exists so a test can assert that a key
was actually wiped.
Shamir¶
Shamir over GF(2^8) with the AES polynomial 0x11b. The workspace's
Cargo.toml says why it is in-crate:
The one in-crate construction is Shamir over GF(256), a secret-sharing scheme and not a primitive.
The distinction matters: Shamir is a scheme built from field arithmetic, not a cryptographic primitive that needs an audited implementation. Building it in-crate means the security argument is in this repository's own code and its own tests.
The implementation draws one polynomial per secret byte, with the coefficients drawn once. Recovery uses Lagrange interpolation at zero and refuses:
- duplicate evaluation points,
- shares that disagree.
One Deliberate Dependency Absence¶
toml is a dev-dependency only of this crate. The module comment says
it: "this crate holds the types and must not learn what a file format is".
The TOML parser lives in ksp, which is where the file is read. ksp-types
takes the configuration type only in tests, so a test can prove the type
parses a real document without the published crate gaining a parser
dependency.
Dependencies¶
ksp-types depends on nothing internal. Its external dependencies are
ciborium, rand, serde, serde_json, sha2, subtle, thiserror and
zeroize, plus toml as a dev-dependency.
Testing¶
- Every identifier's parser, including the rejections: uppercase hex, a
wrong hyphen position, a non-v4 version nibble, a wrong variant nibble, an
agent-level that is not a UUID. - The domain strings are distinct and all end in
-v1. - The AAD is deterministic and changes with any of the five parts.
- The admission boundary:
2x-1refuses,2xadmits. - Shamir:
k-1shares do not recover,kdo, a duplicate index is refused, and disagreeing shares refuse. - The content key is zeroized after erasure, under
test-observer.
Potential Improvements¶
- The
PrincipalIdparser is strict but hand-written. A generated parser would be shorter, but the hand-written one carries the reason for each check, which a generated one would not. evidence.rsholds four structures that share a shape but not a use. They could be generic over a target, but they are deliberately separate so that one cannot be serialised as another.- The capability enums are closed sets with no extension mechanism. Adding a backend capability means a new variant and a compile-time fix everywhere it is matched, which is the intended cost.
See Also¶
- Deep Dive: ksp-record - what consumes this encoding
- Deep Dive: ksp-deletion - what consumes these evidence types