docs(spec): add NanoTDF v1alpha specification suite - #3909
Draft
dmihalcik-virtru wants to merge 2 commits into
Draft
docs(spec): add NanoTDF v1alpha specification suite#3909dmihalcik-virtru wants to merge 2 commits into
dmihalcik-virtru wants to merge 2 commits into
Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Benchmark Statistics
Bulk Benchmark Results
TDF3 Benchmark Results:
|
Contributor
dmihalcik-virtru
force-pushed
the
nanotdf/spec-v1alpha
branch
from
August 21, 2026 01:30
e3740d2 to
1aab99c
Compare
dmihalcik-virtru
force-pushed
the
ictdf/spec-v1alpha
branch
from
August 21, 2026 01:30
bc14a41 to
27527de
Compare
Contributor
X-Test Failure Report |
Contributor
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Benchmark Statistics
Bulk Benchmark Results
TDF3 Benchmark Results:
|
Contributor
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Benchmark Statistics
Bulk Benchmark Results
TDF3 Benchmark Results:
|
Contributor
Add spec/nanotdf/v1alpha/, refactoring the nanotdf version 1 specification into the module architecture shared by the BaseTDF, BinaryTDF, and IC-TDF suites. The refactoring changes document ownership only, not the wire format, algorithms, validation, or security semantics. NanoTDF carries no wrapped key: the symmetric key is derived from an ECDH exchange between an ephemeral key pair and the KAS key pair. That is what keeps fixed overhead under 200 bytes and allows objects to be produced offline. Two modules have no BaseTDF counterpart. NanoTDF-BND owns both the policy binding and the creator signature, because in NanoTDF the binding is a load-bearing wire field sized by a header bitfield rather than a property of an assertion. NanoTDF-PAY exists because payload carriage has its own length field, reserved IV, and implied MAC length. Four BaseTDF modules are deliberately absent: INT (no segmentation or per-segment integrity), ASN (no assertions), MTD (version 1 carries no metadata), and SCH (no external schema artifact -- the byte tables in NanoTDF-PKG are the grammar). Where the source specification is internally inconsistent, this suite states the corrected value and records the correction in NanoTDF-CORE section 6. The eleven corrections include the Policy range (3-257 to 12-714), the Header range (43-584 to 53-1043), the Signature range (97-133 to 97-199), and Policy Key Access (36-136 to 36-324). The Payload range of 14-16,777,218 looks wrong but is correct, and carries a note explaining why so it is not "fixed" later. Both worked examples are reproduced in full in NanoTDF-EX and verified: they decode to 258 and 197 bytes, with every field offset and section length reconciling. The second, at 173 bytes of overhead, substantiates the sub-200-byte claim. Signed-off-by: Dave Mihalcik <dmihalcik@virtru.com>
NanoTDF v1 is a frozen wire format, so this records the flaws rather than changing them. The suite never said how the three-byte IV becomes a GCM nonce. Three readings fit the text and give different ciphertext, so two conforming implementations could produce objects the other cannot open. Both worked vectors were decrypted under all three: only the 24-bit reading, with J0 from GHASH per SP 800-38D Algorithm 4 step 2, reproduces the recorded plaintext and tag. That reading is now stated normatively. A 24-bit nonce space collides at even odds after 4,823 objects, which matters only if a producer reuses an ephemeral key pair -- and the encrypted policy, pinned to the reserved IV 0x000000, then collides with certainty on the first repeat. Short tags are now coupled to payload length: a 64-bit tag over a maximum payload is worth about 43 bits, not 64, and absorbs only 2,048 forgery attempts. SP 800-38D Appendix C Table 2 is reproduced, since it is a shall, not advice, and NanoTDF has no second integrity layer unless a creator signature is present. Also state the 2^40-byte volume bound, which one object cannot approach, and the scale ceiling: 16,777,215 bytes is 327,680 times smaller than a maximal S3 object. Signed-off-by: Dave Mihalcik <dmihalcik@virtru.com>
dmihalcik-virtru
force-pushed
the
ictdf/spec-v1alpha
branch
from
August 21, 2026 02:16
27527de to
b2c8109
Compare
dmihalcik-virtru
force-pushed
the
nanotdf/spec-v1alpha
branch
from
August 21, 2026 02:16
1aab99c to
3cf3280
Compare
Contributor
X-Test Failure Report |
Contributor
|
Contributor
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Benchmark Statistics
Bulk Benchmark Results
TDF3 Benchmark Results:
|
Contributor
Benchmark results, click to expandBenchmark authorization.GetDecisions Results:
Benchmark authorization.v2.GetMultiResourceDecision Results:
Benchmark Statistics
Bulk Benchmark Results
TDF3 Benchmark Results:
|
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #3907.
Proposed Changes
spec/nanotdf/v1alpha.NanoTDF-CORE§6.NanoTDF-EX, with byte-offset parsing tables.spec/README.md.Module layout
NanoTDF-BNDowns both the policy binding and the creator signature, and covers the signature half ofBaseTDF-ASN; in NanoTDF the binding is a load-bearing wire field sized by a header bitfield rather than a property of an assertion.NanoTDF-PAYexists because payload carriage has its own length field, reserved IV, and implied MAC length, which BaseTDF folds intoCOREandINT.Four BaseTDF modules are deliberately absent:
INT(no segmentation and no per-segment integrity — one payload is one AEAD operation),ASN(no assertions),MTD(version 1 carries no metadata and no extension socket), andSCH(no external schema artifact — the byte tables inNanoTDF-PKGare the grammar). The suite README states these boundaries explicitly. There are no extension, profile, or migration documents, because NanoTDF version 1 defines no extension mechanism.Notes for reviewers
The source specification is internally inconsistent in several places. This suite states the corrected value and lists all eleven corrections in
NanoTDF-CORE§6. The substantive ones are size ranges that do not follow from their own constituent fields:The rest are editorial: the Ephemeral ECC Params Enum is called "7-bit" where its own table gives it 3 bits, the source does not say which curve sizes an ECDSA policy binding (it is the ephemeral curve, not the Signature ECC Mode), a cross-reference is left as the placeholder
[section X.X.X.X](), §3.4.2.2 is skipped, protocol0xffis described as experimental with no processing rules, and the §6.1.6 parsing breakdown omits the payload Length field.One figure that looks wrong is correct and has been preserved: the Payload range of 14–16,777,218. The three-byte Length field caps IV + ciphertext + MAC at 16,777,215, and the source's 16,777,204-byte ciphertext maximum pairs with the minimum 8-byte MAC, so a naive max-plus-max sum overshoots.
NanoTDF-CORE§6 carries a note explaining this so it is not "corrected" later.The source's three SVG figures are redrawn as ASCII, since
spec/contains no image assets.Checklist
Testing Instructions
Documentation-only change. Both worked examples were decoded and verified rather than transcribed: each base64 object decodes to its stated length (258 and 197 bytes), every field offset in the
NanoTDF-EXtables lands on a real field boundary, the per-section byte counts sum to the total, and both consume to zero remaining bytes. The per-field hex inNanoTDF-EXwas generated from the decoded binaries. Example 2 has 173 bytes of overhead, which substantiates the format's sub-200-byte claim.Also verified: the corrected size ranges each recompute from their constituent fields and are consistent across
PKG,POL,BND, andKAO; the bitfield diagrams inNanoTDF-PKGdecode the vectors'0x80and0x35configuration bytes correctly; all relative Markdown links resolve; everyNanoTDF-*cross-reference names a real module and an existing section; and no source figure leaks into an owning module. No Go changes, somake lintandmake fmtdo not apply; the repository has no Markdown linter.