add a README and prepare for a merge to main so docs are discoverable

This commit is contained in:
bunnie 2021-11-23 15:47:53 +08:00
parent cbf7ee032f
commit dc05b2b610

32
services/pddb/README.md Normal file
View file

@ -0,0 +1,32 @@
# PDDB
Documentation for the PDDB can be found in the headers of the source files:
- [main.rs](src/main.rs) contains a glossary, project overview, threat model, auditor's notes, and goals.
- [basis.rs](src/backend/basis.rs) gives details on how the data is organized in
the Basis memory space, and contains most of the code for manipulating dictionary
entries stored within the basis cache.
- [dictionary.rs](src/backend/dictionary.rs) will contain most of the code for
manipulating the keys stored in a dictionary cache entry.
- [keys.rs](src/backend/keys.rs) documents the key cache format and on-disk metadataa and data formats.
- [pagetable.rs](src/backend/pagetable.rs) documents the page table format.
- [hw.rs](src/backend/hw.rs) contains all the glue to the SPINOR layer, TRNG, and system time, as well as low-level
routines for formatting the disk.
- [fastspace.rs](src/backend/fastspace.rs) contains the Fast Free Space optimization, which
is a partial record of known free space in the PDDB. The very nature of plausible deniability
requires this quirky structure, as "free space" is the side channel for leaking information about
the existence, or lack of existence, of certain data.
# Why is your RustDoc so Shitty?
Unfortunately, `rustdoc` [can't document binaries](https://github.com/rust-lang/docs.rs/issues/238),
and so the only documentation you'll see generated are for the "frontend" library
portions, which are the API calls you would use to talk to the PDDB. These are
deliberately uninteresting, as we've gone through great effort to make
the bindings are "what you expect" (principle of least surprise).
Howeve, you're probably looking to fix a PDDB bug, audit
the code, or generally figure out what the hell is going on. This means you want
to look at the PDDB as a "binary" and not a "library" -- something RustDoc can't
help you with. As the issue above notes, the fallback is for you to consult the README
file.