Trusty: provenance library workspace (initial import)
This commit is contained in:
140
docs/vocabulary.md
Normal file
140
docs/vocabulary.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Vocabulary crosswalk
|
||||
|
||||
Our words, the standard words, and which is which. Written so an
|
||||
assessor can follow their own vocabulary into this system, and so we can
|
||||
keep a term where ours is genuinely sharper without that being an
|
||||
obstacle.
|
||||
|
||||
This is the ordinary compliance practice of a **mapping**: NIST
|
||||
publishes the same thing between 800-171 and 800-53. The value is not in
|
||||
picking a winner. Picking one would be wrong anyway — XCCDF is
|
||||
configuration scanning, C2PA is media provenance, in-toto is software
|
||||
supply chain, and none was built for a P2P data mesh.
|
||||
|
||||
**On sourcing.** Rows marked ✓ were checked against the specification
|
||||
during this session. Rows marked ~ are from working knowledge and want
|
||||
confirming before they go in front of an assessor. A term cited wrongly
|
||||
is worse than a term not cited, because a citation reads as authority.
|
||||
|
||||
---
|
||||
|
||||
## 1. Where we already use the standard word
|
||||
|
||||
Nothing to do here. Listed so a reader can stop looking.
|
||||
|
||||
| ours | standard | source |
|
||||
|---|---|---|
|
||||
| `principal` | principal | Kerberos, AWS IAM, Java security, NIST RBAC ~ |
|
||||
| `delegation` | delegation | NIST RBAC, OAuth 2.0 ~ |
|
||||
| `scope` | scope | OAuth 2.0 ~ |
|
||||
| `grant` | grant | OAuth 2.0, XACML ~ |
|
||||
| `Tier::sql_verb()` → SELECT/INSERT/UPDATE/DELETE | the SQL verbs | ISO SQL ✓ |
|
||||
| `canonical_json()` | JSON Canonicalization Scheme | RFC 8785 ✓ |
|
||||
| Ed25519, SHA-256, SipHash-2-4 | same | RFC 8032, FIPS 180-4 ✓ |
|
||||
|
||||
---
|
||||
|
||||
## 2. Where we invented a word and a standard exists
|
||||
|
||||
This is the list that matters.
|
||||
|
||||
### 2.1 `Stance` — the verdict
|
||||
|
||||
**Adopt the standard.** XCCDF is NIST's own, it is what a SCAP-literate
|
||||
assessor reads, and our three values map exactly onto three of its nine.
|
||||
|
||||
| ours | XCCDF `rule-result` ✓ |
|
||||
|---|---|
|
||||
| `Clean` | `pass` |
|
||||
| `Violated` | `fail` |
|
||||
| `Unverifiable` | `unknown` |
|
||||
|
||||
XCCDF's full set is `pass`, `fail`, `error`, `unknown`, `notapplicable`,
|
||||
`notchecked`, `notselected`, `informational`, `fixed`.
|
||||
|
||||
**The one reservation.** `Unverifiable` says *why* nothing is known —
|
||||
the evidence could not be checked — where `unknown` covers that and
|
||||
several other cases. Ours is more precise; theirs is recognisable. For a
|
||||
verdict an outsider reads, recognisable wins.
|
||||
|
||||
**Prior art worth knowing:** OCSP answers the same shape with `good` /
|
||||
`revoked` / `unknown` ~. Three values, and the third is "we cannot say"
|
||||
— the same design decision, reached independently, which is a good sign
|
||||
the three-value shape is right.
|
||||
|
||||
### 2.2 `Annotation` — a claim about a datum
|
||||
|
||||
| ours | C2PA ✓ | in-toto ✓ |
|
||||
|---|---|---|
|
||||
| `Annotation` | **assertion** — a statement the signer makes about the asset | **predicate** |
|
||||
| the signed row carrying it | **claim** — the signed container grouping assertions | **Statement** (`_type`, `subject`, `predicateType`, `predicate`) |
|
||||
| `ProofBundle` | **manifest** — assertions + claim + signature as one verifiable unit | — |
|
||||
| `content_tag` | the asset | **subject** |
|
||||
|
||||
**Keep ours, and say what it maps to.** C2PA's *assertion* is the closest
|
||||
single word, and the C2PA shape is genuinely similar: individual
|
||||
statements, grouped and signed together. But their *claim* and *manifest*
|
||||
have media-provenance meanings that would mislead here, and adopting one
|
||||
word of a three-word system imports the confusion without the benefit.
|
||||
|
||||
The mapping is the deliverable, not a rename.
|
||||
|
||||
### 2.3 The hash names
|
||||
|
||||
| ours | standard | note |
|
||||
|---|---|---|
|
||||
| `row_hash` | Merkle leaf hash ~ | ours is a keyed MAC, theirs usually is not |
|
||||
| `anchor_hash` | Signed Tree Head, RFC 6962 ~ | needs checking before it goes in a filing |
|
||||
|
||||
**Do not rename.** These are frozen byte shapes; the field names feed
|
||||
hashed payloads, and renaming a key that feeds a hash silently breaks
|
||||
every artifact already signed under the old spelling. See the lesson
|
||||
`freeze-tokens-for-hashed-keys`.
|
||||
|
||||
### 2.4 Smaller ones
|
||||
|
||||
| ours | standard | verdict |
|
||||
|---|---|---|
|
||||
| `producer registry` | PKI **issuer** ~; C2PA **claim generator** ✓ | keep — ours is a registry of keys, not an issuer of certificates |
|
||||
| `Tier` | NIST RBAC **operation** ~ | keep — ours is a *damage* taxonomy that happens to map 1:1 onto the SQL verbs, which "operation" does not convey |
|
||||
| `content_tag` | in-toto **subject** ✓; content-addressing **CID** ~ | keep, map to `subject` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Genuinely ours
|
||||
|
||||
No standard equivalent found. These are the ideas worth defending as
|
||||
novel rather than translating.
|
||||
|
||||
- **chain-break-as-event.** A monitored condition failing is recorded as
|
||||
a first-class row rather than raised as an error, so the violation is
|
||||
evidence rather than something a log swallowed.
|
||||
- **One chain per `(data, node)`.** Nobody writes to anybody else's
|
||||
chain, so a node cannot forge a record it did not make, and the picture
|
||||
is recovered by merging rather than by agreeing.
|
||||
- **Tier → RLS with no translation layer.** The four tiers *are* the
|
||||
four SQL verbs, so a grant compiles to a row-level-security predicate
|
||||
directly. The translation layer is where an application's idea of a
|
||||
permission and the database's drift apart.
|
||||
- **`rows_valid` / `fully_signed` / `continuous` / `intact()`.** Four
|
||||
separate questions instead of one boolean, because "did the signatures
|
||||
check" and "was anything unsigned" and "was a break recorded" have
|
||||
different answers and different consequences.
|
||||
|
||||
---
|
||||
|
||||
## 4. What to do with this
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Rename now** | `Stance` → XCCDF's `pass` / `fail` / `unknown`. Days old, one consumer, cheap. |
|
||||
| **Map, don't rename** | `Annotation`, `ProofBundle`, `content_tag`, `Tier`, `producer registry`. Load-bearing across crates and, for some, already in a committed migration. |
|
||||
| **Never rename** | `row_hash`, `anchor_hash`, and any other key feeding a hashed payload. |
|
||||
| **Defend as novel** | section 3. |
|
||||
|
||||
**Sources checked this session:** [NIST XCCDF 1.2
|
||||
schema](https://csrc.nist.gov/schema/xccdf/1.2/xccdf_1.2.xsd) ·
|
||||
[OpenSCAP manual](https://static.open-scap.org/openscap-1.2/oscap_user_manual.html) ·
|
||||
[C2PA specification](https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html) ·
|
||||
[in-toto Statement
|
||||
layer](https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md)
|
||||
Reference in New Issue
Block a user