diff --git a/POUFs/reference-POUF/pouf1.md b/POUFs/reference-POUF/pouf1.md index b4b8c67a..12d5be5e 100644 --- a/POUFs/reference-POUF/pouf1.md +++ b/POUFs/reference-POUF/pouf1.md @@ -22,6 +22,11 @@ This POUF uses a subset of the JSON object format, with floating-point numbers o In this POUF, metadata files are hosted on the repository using HTTP. The filenames for these files are ROLE.json where ROLE is the associated role name (root, targets, snapshot, or timestamp). A client downloads these files by HTTP post request. The location of the repository is preloaded onto the clients. +Snapshot Merkle trees in this implementation will use sha256 to compute the digest of each node, and will use the following procedures for computing node digests: +* A leaf digest is the sha256 hash of the cannonical json encoding of its `leaf_contents`. +* An internal node's digest is the sha256 hash of its left child's digest + it's right child's digest, using utf-8 encoding. +* The `path_directions` and `merkle_path` for each snapshot Merkle metadata file provide information needed to reconstruct the Merkle tree. For each node in the tree, starting with the given leaf node, the next `path_directions` will be -1 if the corresponding `merkle_path` is a right sibling of the current node, or 1 if it is a left sibling. So, a `path_direction` of -1 means that the parent node's digest will be the hash of the current node's digest + the next `merkle_path` digest (as the `merkle_path` is a right sibling). + ## Message Handler Table This table lists the message handlers supported by the reference implementation. @@ -336,6 +341,7 @@ The timestamp file is signed by a timestamp key. It indicates the "spec_version" : SPEC_VERSION, "version" : VERSION, "expires" : EXPIRES, + ("merkle_root": ROOT_HASH), "meta" : METAFILES } @@ -361,6 +367,8 @@ The timestamp file is signed by a timestamp key. It indicates the HASH is the hexdigest of the cryptographic function computed on the snapshot.json metadata file. + ROOT_HASH is the hash of the Merkle tree's root node. + ### mirrors.json The mirrors.json file is signed by the mirrors role. It indicates which mirrors are active and believed to be mirroring specific parts of the @@ -401,6 +409,22 @@ This behavior can be modified by the client code that uses the framework to, for example, randomly select from the listed mirrors. +### Snapshot Merkle metadata + +Snapsot Merkle metadata is not signed. It lists version information for a metadata file, and a path through the Merkle tree to verify this information. + +``` +{ “leaf_contents”: {METAFILES}, + “merkle_path”: {INDEX:HASH} + “path_directions”:{INDEX:DIR} +} +``` + +Where `METAFILES` is the version information as defined for snapshot metadata, +`INDEX` provides the ordering of nodes, `HASH` is the sha256 hash of the sibling node, +and `DIR` is a `1` or `0` that indicates whether the given node is a left or right sibling. + + # Security Audit This profile was included in TUF security audits available at https://theupdateframework.github.io/audits.html.