delegation docs
diff --git a/src/interchange/mod.rs b/src/interchange/mod.rs
index 8b8eb28..470ad25 100644
--- a/src/interchange/mod.rs
+++ b/src/interchange/mod.rs
@@ -34,7 +34,7 @@
/// Write a struct to a stream.
///
- /// Note: This *MUST* writer the bytes canonically for hashes to line up correctly in other
+ /// Note: This *MUST* write the bytes canonically for hashes to line up correctly in other
/// areas of the library.
fn to_writer<W, T: Sized>(writer: W, value: &T) -> Result<()>
where
@@ -51,19 +51,30 @@
/// JSON data interchange.
///
/// # Schema
-///
+///
/// This doesn't use JSON Schema because that specification language is rage inducing. Here's
/// something else instead.
///
/// ## Common Entities
///
/// `NATURAL_NUMBER` is an integer in the range `[1, 2**32)`.
-///
+///
/// `EXPIRES` is an ISO-8601 date time in format `YYYY-MM-DD'T'hh:mm:ss'Z'`.
///
/// `KEY_ID` is the base64url encoded value of `sha256(spki(pub_key))`.
///
-/// `PUB_KEY` is a base64url encoded `SubjectPublicKeyInfo` DER public key.
+/// `PUB_KEY` is the following:
+///
+/// ```bash
+/// {
+/// "type": KEY_TYPE,
+/// "value": PUBLIC
+/// }
+/// ```
+///
+/// `PUBLIC` is a base64url encoded `SubjectPublicKeyInfo` DER public key.
+///
+/// `KEY_TYPE` is a string (either `rsa` or `ed25519`).
///
/// `HASH_VALUE` is a base64url encoded hash value.
///
@@ -90,7 +101,7 @@
/// ```
///
/// `SIGNED` is one of:
-///
+///
/// - `RootMetadata`
/// - `SnapshotMetadata`
/// - `TargetsMetadata`
@@ -115,9 +126,9 @@
/// "timestamp": ROLE_DESCRIPTION
/// }
/// ```
-///
+///
/// `ROLE_DESCRIPTION` is the following:
-///
+///
/// ```bash
/// {
/// "threshold": NATURAL_NUMBER,
@@ -137,7 +148,7 @@
/// }
/// }
/// ```
-///
+///
/// `META_PATH` is a string.
///
///
diff --git a/src/lib.rs b/src/lib.rs
index 87a6bde..ca94c60 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -10,9 +10,9 @@
//! Additionally, the following two papers are valuable supplements in understanding how to
//! actually implement TUF for a community repository.
//!
-//! - [The Diplomat Paper
+//! - [The Diplomat paper
//! (2016)](https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/kuppusamy)
-//! - [The Mercury Paper
+//! - [The Mercury paper
//! (2017)](https://www.usenix.org/conference/atc17/technical-sessions/presentation/kuppusamy)
//!
//! Failure to read the spec and the above papers will likely lead to an implementation that does
@@ -24,9 +24,82 @@
//! way of organizing metadata within a repository. Thus, all TUF implementation could perfectly
//! interoperate. The TUF spec has moved to describing *how a framework should behave* leaving many
//! of the detais up to the implementor. Therefore, there are **zero** guarantees that this library
-//! will work with any other TUF implemenation. Should you want to access a TUF repository that
+//! will work with any other TUF implementation. Should you want to access a TUF repository that
//! uses `rust-tuf` as its backend from another language, ASN.1 modules and metadata schemas are
//! provided that will allow you to interoperate with this library.
+//!
+//! # Implementation Considerations
+//!
+//! ## Key Management
+//!
+//! Part of TUF is that it acts as its own PKI, and there is no integration that needs to be done
+//! for managing keys.
+//!
+//! Note: No two private keys that are generated should ever exist on the same hardware. When a
+//! step says "generate `N` keys," the implication is that these `N` keys are generated on `N`
+//! devices.
+//!
+//! The first set of keys that need to be generated at the root keys that are used to sign the root
+//! metadata. The root should be defined with the following properties:
+//!
+//! - Minimum:
+//! - 3 keys
+//! - threshold of 2
+//! - Recommended:
+//! - 5 keys
+//! - threshold of 3
+//!
+//! If a threshold of root keys are compromised, then the entire system is compromised and TUF
+//! clients will need to be manually updated. Similarly, if some `X` keys are lost such that the
+//! threshold `N` cannot be reached, then clients will also need to be manually updated. Both of
+//! situations are considered critically unsafe. Whatever number of keys are used, it should be
+//! assumed that some small number may be lost or compromised.
+//!
+//! These root keys should be kept offline on secure media.
+//!
+//! ## Delegations
+//!
+//! TUF's most useful feature is the ability to delegate certain roles to sign certain targets.
+//! This is discussed in extensive detail in the aforementioned Diplomat paper. There are three
+//! problems faced when delegating trust in TUF:
+//!
+//! 1. What to do for existent accounts that have not yet created and signed TUF metadata
+//! 2. What to do when a new account registers
+//! 3. What to do when an account uploads a new target and new metadata
+//!
+//! There are several approaches for dealing with the above scenarios. We are only going to discuss
+//! on here as it is the recommended approach. This approach is taken directly from Section 6.1 of
+//! he Diplomat paper
+//!
+//! ### Maximum Security Model
+//!
+//! The top-level targets role delegates to three other roles and are listed in the following order:
+//!
+//! 1. `claimed-projects`
+//! - `terminating: true`
+//! - Delegates to project-specific roles that have registered keys with TUF
+//! 2. `rarely-updated-projects`
+//! - `terminating: true`
+//! - Signs all packages for all projects that have been "abandoned" or left unupdated for a long
+//! time AND have not yet registered keys with TUF
+//! 3. `new-projects`
+//! - `terminating: false`
+//! - Signs all packages for all new projects as well as projects that were relegated to
+//! `rarely-updated-projects`
+//!
+//! The top-level `targets` role as well as `claimed-projects` and `rarely-updated-projects`
+//! **MUST** all use offline keys.
+//!
+//! The critical, manual step is to register new projects with TUF keys and move them into the
+//! `claimed-projects` role. Projects that refuse to register keys should have their packages
+//! periodically moved into the `rarely-updated-projects` role. Projects in either of these two
+//! roles are safe from compromise as their keys are offline. Since the keys used for the above
+//! operation are kept offline, this is periodic, manual process.
+//!
+//! ## Snapshot & Timestamp
+//!
+//! In a community repository, these two keys need to be kept online and will be used to sign new
+//! metadata on every update.
#![deny(missing_docs)]
