Merge pull request #22 from vladimir-v-diaz/detailed_workflow_numbering-issue#16

Fix subsections of detailed workflow: Iissue #16

Author: vladimir-v-diaz

tuf-spec.md

@@ -1,6 +1,6 @@
 # <p align="center">The Update Framework Specification
 
-Last modified: **10 May 2018**
+Last modified: **19 June 2018**
 
 Version: **1.0 (Draft)**
 
@@ -994,193 +994,190 @@ repo](https://github.com/theupdateframework/specification/issues).
 
 ## **5. Detailed Workflows**
 
-* **5.1. The client application**
-
-    0. **Load the trusted root metadata file.** We assume that a good, trusted
-    copy of this file was shipped with the package manager / software updater
-    using an out-of-band process.
-
-    0.1. Note that the expiration of the trusted root metadata file does not
-    matter, because we will attempt to update it in the next step.
-
-    1. **Update the root metadata file.** Since it may now be signed using
-    entirely different keys, the client must somehow be able to establish a
-    trusted line of continuity to the latest set of keys (see Section 6.1). To
-    do so, the client MUST download intermediate root metadata files, until the
-    latest available one is reached.
-
-    1.1. Let N denote the version number of the trusted root metadata file.
-
-    1.2. **Try downloading version N+1 of the root metadata file**, up to some
-    X number of bytes (because the size is unknown). The value for X is set by
-    the authors of the application using TUF. For example, X may be tens of
-    kilobytes. The filename used to download the root metadata file is of the
-    fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file
-    is not available, then go to step 1.8.
-
-    1.3. **Check signatures.** Version N+1 of the root metadata file MUST have
-    been signed by: (1) a threshold of keys specified in the trusted root
-    metadata file (version N), and (2) a threshold of keys specified in the
-    new root metadata file being validated (version N+1).
-
-    1.4. **Check for a rollback attack.** The version number of the trusted
-    root metadata file (version N) must be less than or equal to the version
-    number of the new root metadata file (version N+1). Effectively, this means
-    checking that the version number signed in the new root metadata file is
-    indeed N+1.
-
-    1.5. Note that the expiration of the new (intermediate) root metadata
-    file does not matter yet, because we will check for it in step 1.8.
-
-    1.6. Set the trusted root metadata file to the new root metadata file.
-
-    1.7. Repeat steps 1.1 to 1.7.
-
-    1.8. **Check for a freeze attack.** The latest known time should be lower
-    than the expiration timestamp in the trusted root metadata file.
-
-    1.9. **If the timestamp and / or snapshot keys have been rotated, then
-    delete the trusted timestamp and snapshot metadata files.** This is done
-    in order to recover from fast-forward attacks after the repository has been
-    compromised and recovered. A _fast-forward attack_ happens when attackers
-    arbitrarily increase the version numbers of: (1) the timestamp metadata,
-    (2) the snapshot metadata, and / or (3) the targets, or a delegated
-    targets, metadata file in the snapshot metadata. Please see [the Mercury
-    paper](https://ssl.engineering.nyu.edu/papers/kuppusamy-mercury-usenix-2017.pdf)
-    for more details.
-
-    2. **Download the timestamp metadata file**, up to Y number of bytes
-    (because the size is unknown.) The value for Y is set by the authors of the
-    application using TUF. For example, Y may be tens of kilobytes. The
-    filename used to download the timestamp metadata file is of the fixed form
-    FILENAME.EXT (e.g., timestamp.json).
-
-    2.1. **Check signatures.** The new timestamp metadata file must have been
-    signed by a threshold of keys specified in the trusted root metadata file.
-
-    2.2. **Check for a rollback attack.** The version number of the trusted
-    timestamp metadata file, if any, must be less than or equal to the version
-    number of the new timestamp metadata file.
-
-    2.3. **Check for a freeze attack.** The latest known time should be lower
-    than the expiration timestamp in the new timestamp metadata file.  If so,
-    the new timestamp metadata file becomes the trusted timestamp
-    metadata file.
-
-    3. **Download and check the snapshot metadata file**, up to the number of
-    bytes specified in the timestamp metadata file.  If consistent snapshots
-    are not used (see Section 7), then the filename used to download the
-    snapshot metadata file is of the fixed form FILENAME.EXT (e.g.,
-    snapshot.json).  Otherwise, the filename is of the form
-    VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where VERSION_NUMBER
-    is the version number of the snapshot metadata file listed in the timestamp
-    metadata file.  In either case, the client MUST write the file to
-    non-volatile storage as FILENAME.EXT.
-
-    3.1. **Check against timestamp metadata.** The hashes and version number
-    of the new snapshot metadata file MUST match the hashes and version number
-    listed in timestamp metadata.
-
-    3.2. **Check signatures.** The snapshot metadata file MUST have been signed
-    by a threshold of keys specified in the trusted root metadata file.
-
-    3.3. **Check for a rollback attack.**
-
-    3.3.1. Note that the trusted snapshot metadata file may be checked for
-    authenticity, but its expiration does not matter for the following
+### **The client application**
+
+  **0**. **Load the trusted root metadata file.** We assume that a good, trusted
+  copy of this file was shipped with the package manager or software updater
+  using an out-of-band process.  Note that the expiration of the trusted root
+  metadata file does not matter, because we will attempt to update it in the
+  next step.
+
+  **1**. **Update the root metadata file.**
+  Since it may now be signed using entirely different keys, the client must
+  somehow be able to establish a trusted line of continuity to the latest set
+  of keys (see Section 6.1). To do so, the client MUST download intermediate
+  root metadata files, until the latest available one is reached.
+
+  * **1.1**. Let N denote the version number of the trusted root metadata file.
+
+  * **1.2**. **Try downloading version N+1 of the root metadata file**, up to
+  some X number of bytes (because the size is unknown). The value for X is set
+  by the authors of the application using TUF. For example, X may be tens of
+  kilobytes. The filename used to download the root metadata file is of the
+  fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is
+  not available, then go to step 1.8.
+
+  * **1.3. Check signatures.** Version N+1 of the root metadata file MUST have
+  been signed by: (1) a threshold of keys specified in the trusted root
+  metadata file (version N), and (2) a threshold of keys specified in the new
+  root metadata file being validated (version N+1).
+
+  * **1.4. Check for a rollback attack.** The version number of the trusted
+  root metadata file (version N) must be less than or equal to the version
+  number of the new root metadata file (version N+1). Effectively, this means
+  checking that the version number signed in the new root metadata file is
+  indeed N+1.
+
+  * **1.5**. Note that the expiration of the new (intermediate) root metadata
+  file does not matter yet, because we will check for it in step 1.8.
+
+  * **1.6**. **Set the trusted root metadata file** to the new root metadata
+  file.
+
+  * **1.7**. **Repeat steps 1.1 to 1.7**.
+
+  * **1.8**. **Check for a freeze attack.** The latest known time should be
+  lower than the expiration timestamp in the trusted root metadata file.
+
+  * **1.9**. **If the timestamp and / or snapshot keys have been rotated, then
+  delete the trusted timestamp and snapshot metadata files.** This is done in
+  order to recover from fast-forward attacks after the repository has been
+  compromised and recovered. A _fast-forward attack_ happens when attackers
+  arbitrarily increase the version numbers of: (1) the timestamp metadata, (2)
+  the snapshot metadata, and / or (3) the targets, or a delegated targets,
+  metadata file in the snapshot metadata. Please see [the Mercury
+  paper](https://ssl.engineering.nyu.edu/papers/kuppusamy-mercury-usenix-2017.pdf)
+  for more details.
+
+**2**. **Download the timestamp metadata file**, up to Y number of bytes
+(because the size is unknown.) The value for Y is set by the authors of the
+application using TUF. For example, Y may be tens of kilobytes. The filename
+used to download the timestamp metadata file is of the fixed form FILENAME.EXT
+(e.g., timestamp.json).
+
+  * **2.1**. **Check signatures.** The new timestamp metadata file must have
+  been signed by a threshold of keys specified in the trusted root metadata
+  file.
+
+  * **2.2**. **Check for a rollback attack.** The version number of the trusted
+  timestamp metadata file, if any, must be less than or equal to the version
+  number of the new timestamp metadata file.
+
+  * **2.3**. **Check for a freeze attack.** The latest known time should be
+  lower than the expiration timestamp in the new timestamp metadata file.  If
+  so, the new timestamp metadata file becomes the trusted timestamp metadata
+  file.
+
+**3**. **Download snapshot metadata file**, up to the number of bytes specified
+in the timestamp metadata file.  If consistent snapshots are not used (see
+Section 7), then the filename used to download the snapshot metadata file is of
+the fixed form FILENAME.EXT (e.g., snapshot.json).  Otherwise, the filename is
+of the form VERSION_NUMBER.FILENAME.EXT (e.g., 42.snapshot.json), where
+VERSION_NUMBER is the version number of the snapshot metadata file listed in
+the timestamp metadata file.  In either case, the client MUST write the file to
+non-volatile storage as FILENAME.EXT.
+
+  * **3.1**. **Check against timestamp metadata.** The hashes and version number
+  of the new snapshot metadata file MUST match the hashes and version number
+  listed in timestamp metadata.
+
+  * **3.2**. **Check signatures.** The snapshot metadata file MUST have been
+  signed by a threshold of keys specified in the trusted root metadata file.
+
+  * **3.3**. **Check for a rollback attack.**
+
+    * **3.3.1**. Note that the trusted snapshot metadata file may be checked
+    for authenticity, but its expiration does not matter for the following
     purposes.
 
-    3.3.2. The version number of the trusted snapshot metadata file, if any,
-    MUST be less than or equal to the version number of the new snapshot
-    metadata file.
-
-    3.3.3. The version number of the targets metadata file, and all delegated
-    targets metadata files (if any), in the trusted snapshot metadata file, if
-    any, MUST be less than or equal to its version number in the new snapshot
-    metadata file. Furthermore, any targets metadata filename that was listed
-    in the trusted snapshot metadata file, if any, MUST continue to be listed
-    in the new snapshot metadata file.
-
-    3.4. **Check for a freeze attack.** The latest known time should be lower
-    than the expiration timestamp in the new snapshot metadata file.  If so,
-    the new snapshot metadata file becomes the trusted snapshot metadata
-    file.
-
-    4. **Download and check the top-level targets metadata file**, up to either
-    the number of bytes specified in the snapshot metadata file, or some Z
-    number of bytes. The value for Z is set by the authors of the application
-    using TUF. For example, Z may be tens of kilobytes.  If consistent
-    snapshots are not used (see Section 7), then the filename used to download
-    the targets metadata file is of the fixed form FILENAME.EXT (e.g.,
-    targets.json).  Otherwise, the filename is of the form
-    VERSION_NUMBER.FILENAME.EXT (e.g., 42.targets.json), where VERSION_NUMBER
-    is the version number of the targets metadata file listed in the snapshot
-    metadata file.  In either case, the client MUST write the file to
-    non-volatile storage as FILENAME.EXT.
-
-    4.1. **Check against snapshot metadata.** The hashes (if any), and version
-    number of the new targets metadata file MUST match the trusted snapshot metadata.
-    This is done, in part, to prevent a mix-and-match attack by man-in-the-middle
-    attackers.
-
-    4.2. **Check for an arbitrary software attack.** The new targets metadata file
-    MUST have been signed by a threshold of keys specified in the trusted root
+    * **3.3.2**. The version number of the trusted snapshot metadata file, if
+    any, MUST be less than or equal to the version number of the new snapshot
     metadata file.
 
-    4.3. **Check for a rollback attack.** The version number of the trusted
-    targets metadata file, if any, MUST be less than or equal to the version
-    number of the new targets metadata file.
-
-    4.4. **Check for a freeze attack.** The latest known time should be lower
-    than the expiration timestamp in the new targets metadata file.  If so,
-    the new targets metadata file becomes the trusted targets metadata file.
-
-    4.5. **Perform a preorder depth-first search for metadata about the desired
-    target, beginning with the top-level targets role.**
-
-    4.5.1. If this role has been visited before, then skip this role (so that
-    cycles in the delegation graph are avoided).
-    Otherwise, if an application-specific maximum number of roles have been
-    visited, then go to step 5 (so that attackers cannot cause the client to
-    waste excessive bandwidth or time).
-    Otherwise, if this role contains metadata about the desired target, then go
-    to step 5.
-
-    4.5.2. Otherwise, recursively search the list of delegations in order of
-    appearance.
-
-    4.5.2.1. If the current delegation is a multi-role delegation, recursively
-    visit each role, and check that each has signed exactly the same non-custom
-    metadata (i.e., length and hashes) about the target (or the lack of any
-    such metadata).
-
-    4.5.2.2. If the current delegation is a terminating delegation, then jump
-    to step 5.
-
-    4.5.2.3. Otherwise, if the current delegation is a non-terminating
-    delegation, continue processing the next delegation, if any. Stop the
-    search, and jump to step 5 as soon as a delegation returns a result.
-
-    5. Verify the desired target against its targets metadata
-
-    5.1. If there is no targets metadata about this target, then report that
+    * **3.3.3**. The version number of the targets metadata file, and all
+    delegated targets metadata files (if any), in the trusted snapshot metadata
+    file, if any, MUST be less than or equal to its version number in the new
+    snapshot metadata file. Furthermore, any targets metadata filename that was
+    listed in the trusted snapshot metadata file, if any, MUST continue to be
+    listed in the new snapshot metadata file.
+
+  * **3.4**. **Check for a freeze attack.** The latest known time should be
+  lower than the expiration timestamp in the new snapshot metadata file.  If
+  so, the new snapshot metadata file becomes the trusted snapshot metadata
+  file.
+
+**4**. **Download the top-level targets metadata file**, up to either the
+number of bytes specified in the snapshot metadata file, or some Z number of
+bytes. The value for Z is set by the authors of the application using TUF. For
+example, Z may be tens of kilobytes.  If consistent snapshots are not used (see
+Section 7), then the filename used to download the targets metadata file is of
+the fixed form FILENAME.EXT (e.g., targets.json).  Otherwise, the filename is
+of the form VERSION_NUMBER.FILENAME.EXT (e.g., 42.targets.json), where
+VERSION_NUMBER is the version number of the targets metadata file listed in the
+snapshot metadata file.  In either case, the client MUST write the file to
+non-volatile storage as FILENAME.EXT.
+
+  * **4.1**. **Check against snapshot metadata.** The hashes (if any), and
+  version number of the new targets metadata file MUST match the trusted
+  snapshot metadata.  This is done, in part, to prevent a mix-and-match attack
+  by man-in-the-middle attackers.
+
+  * **4.2**. **Check for an arbitrary software attack.** The new targets
+  metadata file MUST have been signed by a threshold of keys specified in the
+  trusted root metadata file.
+
+  * **4.3**. **Check for a rollback attack.** The version number of the trusted
+  targets metadata file, if any, MUST be less than or equal to the version
+  number of the new targets metadata file.
+
+  * **4.4**. **Check for a freeze attack.** The latest known time should be
+  lower than the expiration timestamp in the new targets metadata file.  If so,
+  the new targets metadata file becomes the trusted targets metadata file.
+
+  * **4.5**. **Perform a preorder depth-first search for metadata about the
+  desired target, beginning with the top-level targets role.**
+
+    * **4.5.1**. If this role has been visited before, then skip this role (so
+    that cycles in the delegation graph are avoided).  Otherwise, if an
+    application-specific maximum number of roles have been visited, then go to
+    step 5 (so that attackers cannot cause the client to waste excessive
+    bandwidth or time).  Otherwise, if this role contains metadata about the
+    desired target, then go to step 5.
+
+    * **4.5.2**. Otherwise, recursively search the list of delegations in order
+    of appearance.
+
+      * **4.5.2.1**. If the current delegation is a multi-role delegation,
+      recursively visit each role, and check that each has signed exactly the
+      same non-custom metadata (i.e., length and hashes) about the target (or
+      the lack of any such metadata).
+
+      * **4.5.2.2**. If the current delegation is a terminating delegation,
+      then jump to step 5.
+
+      * **4.5.2.3**. Otherwise, if the current delegation is a non-terminating
+      delegation, continue processing the next delegation, if any. Stop the
+      search, and jump to step 5 as soon as a delegation returns a result.
+
+**5**. **Verify the desired target against its targets metadata**.
+
+  * **5.1**. If there is no targets metadata about this target, then report that
     there is no such target.
 
-    5.2. Otherwise, download the target (up to the number of bytes specified in
-    the targets metadata), and verify that its hashes match the targets
-    metadata. (We download up to this number of bytes, because in some cases,
-    the exact number is unknown. This may happen, for example, if an external
-    program is used to compute the root hash of a tree of targets files, and
-    this program does not provide the total size of all of these files.)
-    If consistent snapshots are not used (see Section 7), then the filename
-    used to download the target file is of the fixed form FILENAME.EXT (e.g.,
-    foobar.tar.gz).
-    Otherwise, the filename is of the form HASH.FILENAME.EXT (e.g.,
-    c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz),
-    where HASH is one of the hashes of the targets file listed in the targets
-    metadata file found earlier in step 4.
-    In either case, the client MUST write the file to non-volatile storage as
-    FILENAME.EXT.
+  * **5.2**. Otherwise, download the target (up to the number of bytes
+  specified in the targets metadata), and verify that its hashes match the
+  targets metadata. (We download up to this number of bytes, because in some
+  cases, the exact number is unknown. This may happen, for example, if an
+  external program is used to compute the root hash of a tree of targets files,
+  and this program does not provide the total size of all of these files.) If
+  consistent snapshots are not used (see Section 7), then the filename used to
+  download the target file is of the fixed form FILENAME.EXT (e.g.,
+  foobar.tar.gz).  Otherwise, the filename is of the form HASH.FILENAME.EXT
+  (e.g.,
+  c14aeb4ac9f4a8fc0d83d12482b9197452f6adf3eb710e3b1e2b79e8d14cb681.foobar.tar.gz),
+  where HASH is one of the hashes of the targets file listed in the targets
+  metadata file found earlier in step 4.  In either case, the client MUST write
+  the file to non-volatile storage as FILENAME.EXT.
 
 ## **6. Usage**