Clean up language

* Switch many cases of must, optional to MUST, OPTIONAL to match RFC-2119.
* Change Freeze-Attack to use MUST instead of "should".
* Update links to https://theupdateframework.io
* Fix some typos.
* Standardize convention from "(if any)" to ", if any," since that was more
  common.
* Switch from "Check signatures" to "Check or an arbitrary software attack".

Author: erickt

tuf-spec.md

@@ -2,7 +2,7 @@
 
 Last modified: **29 September 2020**
 
-Version: **1.0.8**
+Version: **1.0.9**
 
 We strive to make the specification easy to implement, so if you come across
 any inconsistencies or experience any difficulty, do let us know by sending an
@@ -29,7 +29,7 @@ repo](https://github.com/theupdateframework/specification/issues).
 
    The keywords "MUST," "MUST NOT," "REQUIRED," "SHALL," "SHALL NOT," "SHOULD,"
    "SHOULD NOT," "RECOMMENDED," "MAY," and "OPTIONAL" in this document are to be
-   interpreted as described in RFC 2119.
+   interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
 
 * **1.2. Motivation**
 
@@ -52,9 +52,10 @@ repo](https://github.com/theupdateframework/specification/issues).
 * **1.3. History and credit**
 
    Work on TUF began in late 2009.  The core ideas are based off of previous
-   work done by Justin Cappos and Justin Samuel that identified security flaws
-   in all popular Linux package managers.  More information and current
-   versions of this document can be found at https://www.updateframework.com/
+   work done by Justin Cappos and Justin Samuel that [identified security flaws
+   in all popular Linux package managers](https://theupdateframework.io/papers/attacks-on-package-managers-ccs2008.pdf).
+   More information and current versions of this document can be found at
+   https://theupdateframework.io/
 
    The [Global Environment for Network Innovations](https://www.geni.net/) (GENI)
    and the [National Science Foundation](https://www.nsf.gov/) (NSF) have
@@ -286,10 +287,10 @@ repo](https://github.com/theupdateframework/specification/issues).
       + The root role delegates trust to specific keys trusted for all other
    top-level roles used in the system.
 
-      + The client-side of the framework must ship with trusted root keys for each
+      + The client-side of the framework MUST ship with trusted root keys for each
    configured repository.
 
-      + The root role's private keys must be kept very secure and thus should be
+      + The root role's private keys MUST be kept very secure and thus should be
    kept offline.  If less than a threshold of Root keys are compromised, the
    repository should revoke trust on the compromised keys.  This can be
    accomplished with a normal rotation of root keys, covered in section 6.1
@@ -338,7 +339,7 @@ repo](https://github.com/theupdateframework/specification/issues).
       whose signature has not yet expired, an automated process periodically signs
       a timestamped statement containing the hash of the snapshot file.  Even
       though this timestamp key must be kept online, the risk posed to clients by
-      compromise of this key is minimal.
+      the compromise of this key is minimal.
 
   - **2.1.5 Mirrors role**
 
@@ -545,7 +546,7 @@ repo](https://github.com/theupdateframework/specification/issues).
           "keyval" : {"public" : PUBLIC}
         }
 
-   where PUBLIC is in PEM format and a string.  All RSA keys must be at least
+   where PUBLIC is in PEM format and a string.  All RSA keys MUST be at least
    2048 bits.
 
    The 'ed25519' format is:
@@ -624,11 +625,11 @@ repo](https://github.com/theupdateframework/specification/issues).
 
    A ROLE is one of "root", "snapshot", "targets", "timestamp", or "mirrors".
    A role for each of "root", "snapshot", "timestamp", and "targets" MUST be
-   specified in the key list. The role of "mirror" is optional.  If not
+   specified in the key list. The role of "mirror" is OPTIONAL.  If not
    specified, the mirror list will not need to be signed if mirror lists are
    being used.
 
-   The KEYID must be correct for the specified KEY.  Clients MUST calculate
+   The KEYID MUST be correct for the specified KEY.  Clients MUST calculate
    each KEYID to verify this is correct for the associated key.  Clients MUST
    ensure that for any KEYID represented in this key list and in other files,
    only one unique key has that KEYID.
@@ -974,7 +975,7 @@ repo](https://github.com/theupdateframework/specification/issues).
 * **4.6. File formats: timestamp.json**
 
    The timestamp file is signed by a timestamp key.  It indicates the latest
-   version of the snapshot metadata and is frequently resigned to limit the
+   version of the snapshot metadata and is frequently re-signed to limit the
    amount of time a client can be kept unaware of interference with obtaining
    updates.
 
@@ -1079,7 +1080,7 @@ repo](https://github.com/theupdateframework/specification/issues).
   next step.
 
   **1**. **Update the root metadata file.**
-  Since it may now be signed using entirely different keys, the client must
+  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. Therefore, it
@@ -1098,16 +1099,16 @@ repo](https://github.com/theupdateframework/specification/issues).
   for Y is set by the authors of the application using TUF. For example, Y may
   be 2^10.
 
-  * **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).  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.3. Check for an arbitrary software attack.** 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).  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
+  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.  If the version of the new root metadata file is less than the
@@ -1126,7 +1127,7 @@ repo](https://github.com/theupdateframework/specification/issues).
 
   * **1.8**. **Repeat steps 1.1 to 1.8**.
 
-  * **1.9**. **Check for a freeze attack.** The latest known time should be
+  * **1.9**. **Check for a freeze attack.** The latest known time MUST be
   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
@@ -1151,25 +1152,26 @@ application using TUF. For example, X 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.  If the new timestamp metadata file is not properly signed, discard it,
-  abort the update cycle, and report the signature failure.
+  * **2.1**. **Check for an arbitrary software attack.** The new timestamp
+  metadata file MUST have been signed by a threshold of keys specified in the
+  trusted root metadata 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.**
 
     * **2.2.1**. 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
+    any, MUST be less than or equal to the version 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.2.2**. The version number of the snapshot metadata file in the
     trusted timestamp metadata file, if any, MUST be less than or equal to its
     version number in the new timestamp metadata file.  If not, discard the new
-    timestamp metadadata file, abort the update cycle, and report the failure.
+    timestamp metadata file, abort the update cycle, and report the failure.
 
-  * **2.3**. **Check for a freeze attack.** The latest known time should be
+  * **2.3**. **Check for a freeze attack.** The latest known time MUST 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.  If the new timestamp metadata file has expired, discard it, abort the
@@ -1189,26 +1191,27 @@ VERSION_NUMBER is the version number of the snapshot metadata file listed in
 the timestamp metadata file.
 
   * **3.1**. **Check against timestamp metadata.** The hashes and version
-  number of the new snapshot metadata file MUST match the hashes (if any) and
+  number of the new snapshot metadata file MUST match the hashes, if any, and
   version number listed in the trusted 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 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.2**. **Check for an arbitrary software attack.** 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.** The version number of the targets
-  metadata file, and all delegated targets metadata files (if any), in the
+  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.  If any of
-  these conditions are not met, discard the new snapshot metadadata file, abort
+  these conditions are not met, discard the new snapshot metadata file, abort
   the update cycle, and report the failure.
 
-  * **3.4**. **Check for a freeze attack.** The latest known time should be
+  * **3.4**. **Check for a freeze attack.** The latest known time MUST 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. If the new snapshot metadata file is expired, discard it, abort the
@@ -1228,7 +1231,7 @@ VERSION_NUMBER is the version number of the targets metadata file listed in the
 snapshot metadata file.
 
   * **4.1**. **Check against snapshot metadata.** The hashes and version
-  number of the new targets metadata file MUST match the hashes (if any) and
+  number of the new targets metadata file MUST match the hashes, if any, and
   version number listed in the trusted snapshot metadata.  This is done, in
   part, to prevent a mix-and-match attack by man-in-the-middle attackers.  If
   the new targets metadata file does not match, discard it, abort the update
@@ -1239,7 +1242,7 @@ snapshot metadata file.
   trusted root metadata file.  If the new targets metadata file is not signed
   as required, discard it, abort the update cycle, and report the failure.
 
-  * **4.3**. **Check for a freeze attack.** The latest known time should be
+  * **4.3**. **Check for a freeze attack.** The latest known time MUST 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.  If
   the new targets metadata file is expired, discard it, abort the update cycle,
@@ -1248,7 +1251,7 @@ snapshot metadata file.
   * **4.4**. **Persist targets metadata.** The client MUST write the file to
   non-volatile storage as FILENAME.EXT (e.g. targets.json).
 
-  * **4.5**. **Perform a preorder depth-first search for metadata about the
+  * **4.5**. **Perform a pre-order depth-first search for metadata about the
   desired target, beginning with the top-level targets role.**  Note: If
   any metadata requested in steps 4.4.1 - 4.4.2.3 cannot be downloaded nor
   validated, end the search and report that the target cannot be found.
@@ -1297,7 +1300,7 @@ snapshot metadata file.
 
 ## **6. Usage**
 
-   See https://www.theupdateframework.com/ for discussion of recommended usage
+   See https://theupdateframework.io/ for discussion of recommended usage
    in various situations.
 
 * **6.1. Key management and migration**
@@ -1377,7 +1380,7 @@ snapshot metadata file.
     the cryptographic function) from all digests in the referred file.
 
     Additionally, the timestamp metadata (timestamp.json) should also be
-    written to non-volatile storage whenever it is updated. It is optional for
+    written to non-volatile storage whenever it is updated. It is OPTIONAL for
     an implementation to write identical copies at
     version_number.timestamp.json for record-keeping purposes, because a
     cryptographic hash of the timestamp metadata is usually not known in