Merge pull request #24 from vladimir-v-diaz/revise_steps_requiring_failure_issue#21

Report failure for update steps that require it.  Fix issue #21

Author: vladimir-v-diaz

tuf-spec.md

@@ -996,6 +996,11 @@ repo](https://github.com/theupdateframework/specification/issues).
 
 ### **The client application**
 
+  Note: If a step in the following workflow does not succeed (e.g., the update
+  is aborted because a new metadata file was not signed), the client should
+  still be able to update again in the future. Errors raised during the update
+  process should not leave clients in an unrecoverable state.
+
   **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
@@ -1020,13 +1025,19 @@ repo](https://github.com/theupdateframework/specification/issues).
   * **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).
+  root metadata file being validated (version N+1).  If version N+1 is not
+  signed as required, discard it, abort the update cycle, and report the
+  signature failure.  On the next update cycle, begin at step 0 and version N
+  of the root metadata file.
 
   * **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.
+  indeed N+1.  If the version of the new root metadata file is less than the
+  trusted metadata file, discard it, abort the update cycle, and report the
+  rollback attack.  On the next update cycle, begin at step 0 and version N of
+  the root metadata file.
 
   * **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.
@@ -1037,7 +1048,10 @@ repo](https://github.com/theupdateframework/specification/issues).
   * **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.
+  lower than the expiration timestamp in the trusted root metadata file
+  (version N).  If the trusted root metadata file has expired, abort the update
+  cycle, report the potential freeze attack.  On the next update cycle, begin
+  at step 0 and version N of the 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
@@ -1057,16 +1071,20 @@ used to download the timestamp metadata file is of the fixed form FILENAME.EXT
 
   * **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.
+  file.  If the new timestamp metadata file is not properly signed, discard it,
+  abort the update cycle, and report the signature failure.
 
   * **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.
+  number of the new timestamp metadata file.  If the new timestamp metadata
+  file is older than the trusted timestamp metadata file, discard it, abort the
+  update cycle, and report the potential rollback attack.
 
   * **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.
+  file.  If the new timestamp metadata file has expired, discard it, abort the
+  update cycle, and report the potential freeze attack.
 
 **3**. **Download snapshot metadata file**, up to the number of bytes specified
 in the timestamp metadata file.  If consistent snapshots are not used (see
@@ -1077,12 +1095,16 @@ 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
+  * **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.
+  listed in timestamp metadata.  If hashes and version do not match, discard
+  the new snapshot metadata, abort the update cycle, and report the failure.
 
-  * **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.2**. **Check signatures.** The new snapshot metadata file MUST have
+  been signed by a threshold of keys specified in the trusted root metadata
+  file.  If the new snapshot metadata file is not signed as required, discard
+  it, abort the update cycle, and report the signature failure.
 
   * **3.3**. **Check for a rollback attack.**
 
@@ -1092,19 +1114,24 @@ non-volatile storage as FILENAME.EXT.
 
     * **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.
+    metadata file.  If the new snapshot metadata file is older than the trusted
+    metadata file, discard it, abort the update cycle, and report the potential
+    rollback attack.
 
     * **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.
+    listed in the new snapshot metadata file.  If any of these conditions are
+    not met, discard the new snaphot metadadata file, abort the update cycle,
+    and report the failure.
 
   * **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.
+  file. If the new snaphshot metadata file is expired, discard it, abort the
+  update cycle, and report the potential freeze attack.
 
 **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
@@ -1120,23 +1147,29 @@ 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.
+  by man-in-the-middle attackers.  If the new targets metadata file does not
+  match, discard it, abort the update cycle, and report the failure.
 
   * **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.
+  trusted root metadata file.  If the new targets metadat file is not signed
+  as required, discard it, abort the update cycle, and report the failure.
 
   * **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.
+  number of the new targets metadata file.  If the new targets metadata file is
+  older than the trusted targets metadata file, discard it, abort the update
+  cycle, and report the potential rollback attack.
 
   * **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.
+  the new targets metadata file becomes the trusted targets metadata file.  If
+  the new targets metadata file is expired, discard it, abort the update cycle,
+  and report the potential freeze attack.
 
   * **4.5**. **Perform a preorder depth-first search for metadata about the
   desired target, beginning with the top-level targets role.**  Note: If
-  metadata requested in steps 4.5.1 - 4.5.2.3 cannot be downloaded nor
+  any metadata requested in steps 4.5.1 - 4.5.2.3 cannot be downloaded nor
   validated, end the search and report that the target cannot be found.
 
     * **4.5.1**. If this role has been visited before, then skip this role (so
@@ -1163,8 +1196,8 @@ non-volatile storage as FILENAME.EXT.
 
 **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.1**. If there is no targets metadata about this target, abort the
+  update cycle and 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