appcore-dnt
English guide | Guia em português | Guide français
Generic DNT encrypted container contracts and helpers.
DNT is a versioned binary envelope for arbitrary bytes. It authenticates the
canonical header as AEAD additional data and keeps cryptographic keys outside
the file through an explicit key-provider contract. File extensions such as
.dnt, .dntj, .dntb and .dnto are usage conventions only.
Writers can opt into compact payload storage with
DntSealOptions::compact_payload() or the authenticated
DNT_FLAG_PAYLOAD_DEFLATE flag. Compact mode compresses the codec output with
zlib-wrapped DEFLATE at a balanced level before encryption; normal DNT remains the default.
Compact mode is best for JSON, snapshots, logs and backups. Prefer normal mode
for small, already-compressed, already-encrypted or size-sensitive secret
material.
The 32-bit header flag field is partitioned. Low bits are reserved for DNT
envelope behavior; high bits are authenticated caller/application flags. Use
dnt_user_flag, dnt_compose_flags, DntFlags or
DntSealOptions::with_user_flag instead of manual shifts.
Use DNT when the file must remain portable while still being bound to one application, tenant, content type, codec and key identifier. It is useful for snapshots, backup bundles, durable outbox files, sync packages and local secret material. Plain JSON or raw binary is smaller and faster only when the caller does not need confidentiality, authenticated metadata, context binding, rekey, versioned migration or atomic verified writes.
For file reads, prefer open_owned or read_verified after fs::read.
They decrypt the owned envelope buffer in place. Use open when the caller only
has a borrowed slice.
read_verified requires DntOpenOptions.max_payload_bytes and rejects an
oversized file before reading it into a complete buffer. V1 encrypted metadata
is limited to 64 KiB. Call OpenedDnt::zeroize_plaintext as soon as returned
plaintext and encrypted metadata are no longer needed.
The release comparator warms each path, separates disk space from latency, and reports median, p95, p99, maximum, mean, deviation and semantic throughput for plain reads, DNT open, seal and rekey:
Observed on an Apple M1 release run:
- repetitive JSON used 1,048,557 bytes as plaintext, 1,048,746 bytes as normal DNT and 4,403 bytes as compact DNT; median warm read/open was 42.7 us, 5.51 ms and 321.2 us respectively;
- incompressible binary used 1,048,576, 1,048,773 and 1,048,949 bytes; median read/open was 42.3 us, 5.51 ms and 6.33 ms;
- a 65-byte secret used 65, 252 and 254 bytes; median read/open was 14.5 us, 17.7 us and 23.8 us.
The compact JSON path is faster because it authenticates and decrypts about 4 KiB before inflating, instead of processing about 1 MiB of ciphertext. This does not generalize to incompressible or tiny payloads. The complete environment, p95/p99, seal, rekey, throughput and limitations are in the measured benchmark. Plaintext is a performance baseline only and has none of DNT's security properties.