Merge pull request #113 from joshuagl/joshuagl/POUF1

Suggested changes to TAP 11 and POUF 1

Author: JustinCappos

POUFs/reference-POUF/pouf1.md

@@ -1,21 +1,24 @@
 * POUF: 1
 * Title: Reference Implementation Using Canonical JSON
-* Version: 1
-* Last-Modified: 27-June-2019
-* Author: Marina Moore
+* Version: 2
+* Last-Modified: 06-May-2020
+* Author: Marina Moore, Joshua Lock
 * Status: Draft
 * TUF Version Implemented: 1.0
+* Implementation Version(s) Covered: v0.12.*
 * Content-Type: text/markdown
 * Created: 25-November-2018
 
 # Abstract
 This POUF describes the protocol, operations, usage, and formats for the TUF reference implementation written in Python by NYU.
 
-The reference implementation includes all required features of the TUF standard, as well as many of the optional features as a reference for anyone wishing to implement TUF. The implementation uses canonical JSON encoding.
+The reference implementation includes all required features of the TUF standard, as well as many of the optional features as a reference for anyone wishing to implement TUF. The implementation uses Canonical JSON encoding.
+
+This version of the POUF covers v0.12.* of the reference implementation and has been updated to reflect that: snapshot.json only lists targets metadata (top-level and delegated), and timestamp.json includes hashes and length in METAFILES.
 
 # Protocol
 
-This POUF uses a subset of the JSON object format, with floating-point numbers omitted. When calculating the digest of an object, we use the "canonical JSON" subdialect as described at http://wiki.laptop.org/go/Canonical_JSON.
+This POUF uses a subset of the JSON object format, with floating-point numbers omitted. When calculating the digest of an object, we use the "canonical JSON" subdialect as described at http://wiki.laptop.org/go/Canonical_JSON and implemented in [securesystemslib](https://github.com/secure-systems-lab/securesystemslib/blob/master/securesystemslib/formats.py#L666).
 
 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.
 
@@ -162,7 +165,10 @@ The "signed" portion of root.json is as follows:
              , ... }
        }
 
-   SPEC_VERSION is the version number of the specification using semantic versioning.
+   SPEC_VERSION is the version number of the specification using [semantic versioning](https://semver.org/spec/v2.0.0.html).
+   For purposes of ensuring the spec_version matches during an update, the reference
+   implementation considers all  spec_version's with the same major version number to
+   be a match.
 
    CONSISTENT_SNAPSHOT is a boolean indicating whether the repository supports
    consistent snapshots.
@@ -190,9 +196,8 @@ The "signed" portion of root.json is as follows:
 
   ### snapshot.json
   The snapshot.json file is signed by the snapshot role.  It lists the version
-     numbers of all metadata on the repository, excluding timestamp.json and
-     mirrors.json.  For the root role, the hash(es), size, and version number
-     are listed.
+     numbers of the top-level targets metadata and all delegated targets
+     metadata on the repository.
 
      The "signed" portion of snapshot.json is as follows:
 
@@ -213,8 +218,8 @@ The "signed" portion of root.json is as follows:
      METAPATH is the the metadata file's path on the repository relative to the
      metadata base URL.
 
-     VERSION is listed for the root file
-     and all other roles available on the repository.
+     VERSION is the integer version number listed in the metdata file at
+     METAPATH.
 
   ### targets.json and delegated target roles
   The "signed" portion of targets.json is as follows:
@@ -242,6 +247,9 @@ The "signed" portion of root.json is as follows:
    It is allowed to have a TARGETS object with no TARGETPATH elements.  This
    can be used to indicate that no target files are available.
 
+   LENGTH is an integer that specifies the size in bytes of the file at
+   TARGETPATH.
+
    HASHES is a dictionary that specifies one or more hashes, including
    the cryptographic hash function.  For example: { "sha256": HASH, ... }. It
    is required for delegated roles, and optional for all others. HASH is the
@@ -331,9 +339,27 @@ The timestamp file is signed by a timestamp key.  It indicates the
          "meta" : METAFILES
        }
 
-   METAFILES is the same is described for the snapshot.json file.  In the case
-   of the timestamp.json file, this will commonly only include a description of
-   the snapshot.json file.
+   METAFILES is an object whose format is the following:
+
+         { METAPATH : {
+               "version" : VERSION,
+               "length" : LENGTH,
+               "hashes" : HASHES }
+           , ...
+         }
+
+     METAPATH is the the snapshot metadata file's path on the repository
+     relative to the metadata base URL.
+
+     VERSION is the integer version number listed in snapshot.json.
+
+     LENGTH is an integer that specifies the size in bytes of the snapshot.json
+     metadata file.
+
+     HASHES is a dictionary that specifies one or more hashes, including
+     the cryptographic hash function.  For example: { "sha256": HASH, ... }.
+     HASH is the hexdigest of the cryptographic function computed on the
+     snapshot.json metadata file.
 
 ### mirrors.json
 The mirrors.json file is signed by the mirrors role.  It indicates which
@@ -377,3 +403,10 @@ for example, randomly select from the listed mirrors.
 
 # Security Audit
 This profile was included in TUF security audits available at https://theupdateframework.github.io/audits.html.
+
+# Version History
+
+## 2
+Updated to reflect the latest (v0.12.2) reference implementation.
+* snapshot.json lists only the top-level and delegated targets metadata
+* timestamp.json includes hashes and length of snapshot.json

README.md

@@ -9,11 +9,11 @@
 * [TAP 6: Include specification version in metadata](tap6.md)
 * [TAP 9: Mandatory metadata signing schemes](tap9.md)
 * [TAP 10: Remove native support for compressed metadata](tap10.md)
+* [TAP 11: Using POUFs for Interoperability](tap11.md)
 
 ## Draft
 
 * [TAP 8: Key rotation and explicit self-revocation](tap8.md)
-* [TAP 11: Using POUFs for Interoperability](tap11.md)
 * [TAP 12: Improving keyid flexibility](tap12.md)
 
 ## Rejected

tap11.md

@@ -1,9 +1,9 @@
-* TAP:
+* TAP: 11
 * Title: Using POUFs for Interoperability
 * Version: 1
-* Last-Modified: 26-June-2019
+* Last-Modified: 17-Jul-2020
 * Author: Marina Moore, Santiago Torres, Trishank Kuppusamy, Sebastien Awwad, Justin Cappos
-* Status: Draft
+* Status: Accepted
 * Content-Type: text/markdown
 * Created: 9-November-2018
 
@@ -50,7 +50,7 @@ These statuses are maintained by the POUF author and included in the header of t
 They allow POUFs in all stages to be made available while clarifying which are ready to be implemented.
 
 POUFs may be changed over time to account for changes to the TUF specification, updates to protocols, or other design changes.
-To indicate that a change has occurred, new version numbers should be assigned to the POUF. The version number will be stored in the POUF header as described in {#pouf-format}.
+To indicate that a change has occurred, new version numbers should be assigned to the POUF. The version number will be stored in the POUF header as described in [POUF Format](#pouf-format).
 In order for a POUF implementer to know if their implementation needs to be updated, any changes that make a POUF not backwards compatible should result in a new version number.
 The format and management of version numbers is left to the POUF author, but standard formats like Semantic Versioning (https://semver.org/) are recommended for clarity and consistency with TUF. In addition, POUF authors may refer to how TUF manages updates to ensure that non backwards compatible POUFs do not interfere with TUF communication.
 
@@ -67,15 +67,15 @@ For example, implementers a and b may implement POUF p1.
 This means that a and b will be able to interoperate, but they will not necessarily be able to interoperate with implementers of POUF p2.
 It is important that implementations list in their documentation the POUF(s) that are supported as well as the version numbers for these POUF(s) so that other implementers looking to interoperate may refer to the relevant POUF.
 
-To ensure that a POUF follows the TUF specification and that it does not introduce new security issues, we recommend a security audit for POUFs as described in {#security-audit}.
+To ensure that a POUF follows the TUF specification and that it does not introduce new security issues, we recommend a security audit for POUFs as described in [Security Audit](#security-audit).
 In addition to checking the POUF against the specification, this audit ensures that the encoding method or design decisions do not introduce ambiguity or an insecure implementation.
 The security audit does not guarantee security, but provides some oversight.
 
 ## POUF Storage
 
 If a POUF author wants their POUF to be publicly accessed and reviewed, it should be stored in a public location that can be accessed by other TUF implementers.
 In addition to storing the current POUF, the author may maintain old versions of the POUF to allow existing implementations to continue to refer to them.
-Old versions will have a unique version number in the header as described in {#pouf-format}, and may additionally be named according to the POUF version.
+Old versions will have a unique version number in the header as described in [POUF Format](#pouf-format), and may additionally be named according to the POUF version.
 For example a POUF repository may contain two documents, POUFNAME-1.md and POUFNAME-2.md, that contain version 1 and 2 of the POUF respectively.
 
 A link to a public POUF can be added to the TAP repository through the pull request process.
@@ -95,12 +95,13 @@ At a minimum, a POUF shall contain the following sections:
   * Title:
   * Version:
   * Last-Modified:
-  * Author: optional list of authors' real names and email addrs
+  * Author: optional list of authors' real names and email addresses
   * Status: Draft / In Use / Obsolete
-  * TUF Version Implemented:
+  * TUF Version(s) Implemented: the release version of the TUF specification versions covered by the POUF
+  * Implementation Version(s) Covered: release version information of the implementation versions covered by this Version of the POUF
   * Content-Type: text/markdown
   * Created: date created on, in dd-mmm-yyyy format
-* Abstract: Description of the POUF including an overview of design decisions. If the POUF version has been updated, the changes to the POUF should be described here.
+* Abstract: Description of the POUF including an overview of design decisions. If the POUF version has been updated, a summary of high-level changes to the POUF should be described here.
 * Protocol: The protocol section describes the networking operations of the implementation. This includes the protocol used to transmit data, the location and filenames of any hosted files, and a Message Handler Table. The Message Handler Table will list all messages transmitted by the implementation. Each entry in the Message Handler Table will include the sender, receiver, data, and expected response. All messages in this table must be implemented by anyone using the POUF.
 * Operations: The operations section contains a description of any design elements or features that differ from the TUF specification. This section will describe any optional or additional features that are required for compatibility. The format of data does not need to be described here.
 * Usage: The usage section contains an overview of how data is managed by the implementation. This includes key management, key rotation, server setup, supply chain security, and device registration.
@@ -117,7 +118,8 @@ At a minimum, a POUF shall contain the following sections:
   If mirrors are supported by the POUF, their format should be described here. Information about how mirrors are used may be included in the Operations section of the POUF.
 
   The canonical json description currently in the TUF specification (under "Document Formats") provides an example of the type definitions required for the Formats section of a POUF.
-* Security Audit: The third party security audit as described in {#security-audit}.
+* Security Audit: The third party security audit as described in [Security Audit](#security-audit).
+* Version History: For versions beyond the initial release this should be a list of changes introduced in each new version of the POUF. This section could also map POUF versions to releases of the implementation.
 
 ## Security Audit