json schemas for metadata in docs
diff --git a/src/interchange/mod.rs b/src/interchange/mod.rs
index 7635dba..8b8eb28 100644
--- a/src/interchange/mod.rs
+++ b/src/interchange/mod.rs
@@ -49,6 +49,154 @@
}
/// 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.
+///
+/// `HASH_VALUE` is a base64url encoded hash value.
+///
+/// `METADATA_DESCRIPTION` is the following:
+///
+/// ```bash
+/// {
+/// "version": NATURAL_NUMBER,
+/// "size": NATURAL_NUMBER,
+/// "hashes": {
+/// HASH_ALGORITHM: HASH_VALUE
+/// ...
+/// }
+/// }
+/// ```
+///
+/// ## `SignedMetadata`
+///
+/// ```bash
+/// {
+/// "signatures": [SIGNATURE],
+/// "signed": SIGNED
+/// }
+/// ```
+///
+/// `SIGNED` is one of:
+///
+/// - `RootMetadata`
+/// - `SnapshotMetadata`
+/// - `TargetsMetadata`
+/// - `TimestampMetadata`
+///
+/// The the elements of `signatures` must have unique `key_id`s.
+///
+/// ## `RootMetadata`
+///
+/// ```bash
+/// {
+/// "type": "root",
+/// "version": NATURAL_NUMBER,
+/// "expires": EXPIRES,
+/// "keys": {
+/// KEY_ID: PUB_KEY,
+/// ...
+/// },
+/// "root": ROLE_DESCRIPTION,
+/// "snapshot": ROLE_DESCRIPTION,
+/// "targets": ROLE_DESCRIPTION,
+/// "timestamp": ROLE_DESCRIPTION
+/// }
+/// ```
+///
+/// `ROLE_DESCRIPTION` is the following:
+///
+/// ```bash
+/// {
+/// "threshold": NATURAL_NUMBER,
+/// "key_ids": [KEY_ID]
+/// }
+/// ```
+///
+/// ## `SnapshotMetadata`
+///
+/// ```bash
+/// {
+/// "type": "snapshot",
+/// "version": NATURAL_NUMBER,
+/// "expires": EXPIRES,
+/// "meta": {
+/// META_PATH: METADATA_DESCRIPTION
+/// }
+/// }
+/// ```
+///
+/// `META_PATH` is a string.
+///
+///
+/// ## `TargetsMetadata`
+///
+/// ```bash
+/// {
+/// "type": "timestamp",
+/// "version": NATURAL_NUMBER,
+/// "expires": EXPIRES,
+/// "targets": {
+/// TARGET_PATH: TARGET_DESCRIPTION
+/// ...
+/// },
+/// "delegations": DELEGATIONS
+/// }
+/// ```
+///
+/// `DELEGATIONS` is optional and is described by the following:
+///
+/// ```bash
+/// {
+/// "keys": {
+/// KEY_ID: PUB_KEY,
+/// ...
+/// },
+/// "roles": {
+/// ROLE: DELEGATION,
+/// ...
+/// }
+/// }
+/// ```
+///
+/// `DELEGATION` is:
+///
+/// ```bash
+/// {
+/// "name": ROLE,
+/// "threshold": NATURAL_NUMBER,
+/// "terminating": BOOLEAN,
+/// "key_ids": [KEY_ID],
+/// "paths": [PATH]
+/// }
+/// ```
+///
+/// `ROLE` is a string,
+///
+/// `PATH` is a string.
+///
+/// ## `TimestampMetadata`
+///
+/// ```bash
+/// {
+/// "type": "timestamp",
+/// "version": NATURAL_NUMBER,
+/// "expires": EXPIRES,
+/// "snapshot": METADATA_DESCRIPTION
+/// }
+/// ```
#[derive(Debug, Clone, PartialEq)]
pub struct JsonDataInterchange {}
impl DataInterchange for JsonDataInterchange {
diff --git a/src/lib.rs b/src/lib.rs
index 050c787..87a6bde 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,12 +1,25 @@
//! This crate provides an API for talking to repositories that implement The Update Framework
//! (TUF).
//!
-//! If you are unfamiliar with TUF, you should read up on via the [official
+//! If you are unfamiliar with TUF, you should read up on it via the [official
//! website](http://theupdateframework.github.io/). This crate aims to implement the entirety of
//! the specification as defined at the [head of the `develop`
//! branch](https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt) in the
//! official TUF git repository.
//!
+//! Additionally, the following two papers are valuable supplements in understanding how to
+//! actually implement TUF for a community repository.
+//!
+//! - [The Diplomat Paper
+//! (2016)](https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/kuppusamy)
+//! - [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
+//! not take advantage of all the security guarantees that TUF offers.
+//!
+//! # Interoperability
+//!
//! It should be noted that historically the TUF spec defined exactly one metadata format and one
//! 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
@@ -14,7 +27,6 @@
//! will work with any other TUF implemenation. 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.
-//!
#![deny(missing_docs)]
diff --git a/src/repository.rs b/src/repository.rs
index 10b1e24..cc1d879 100644
--- a/src/repository.rs
+++ b/src/repository.rs
@@ -33,7 +33,7 @@
/// Store signed metadata.
///
- /// Note: This *MUST* canonicalize the bytes before storing them as a read will expect the
+ /// Note: This **MUST** canonicalize the bytes before storing them as a read will expect the
/// hashes of the metadata to match.
fn store_metadata<M>(
&mut self,
