diff --git a/tuf-spec.md b/tuf-spec.md index 0bf40a4..05ee4d2 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -3,7 +3,7 @@ Title: The Update Framework Specification Shortname: TUF Status: LS Abstract: A framework for securing software update systems. -Date: 2022-09-09 +Date: 2023-03-02 Editor: Justin Cappos, NYU Editor: Trishank Karthik Kuppusamy, Datadog Editor: Joshua Lock, Verizon @@ -16,7 +16,7 @@ Boilerplate: copyright no, conformance no Local Boilerplate: header yes Markup Shorthands: css no, markdown yes Metadata Include: This version off, Abstract off -Text Macro: VERSION 1.0.31 +Text Macro: VERSION 1.0.32 Note: We strive to make the specification easy to implement, so if you come @@ -518,6 +518,8 @@ http://wiki.laptop.org/go/Canonical_JSON). ## File formats: general principles ## {#file-formats-general-principles} +### Object format ### {#file-formats-object-format} + All signed metadata objects have the format: 
@@ -545,8 +547,9 @@ All signed metadata objects have the format:
       ::
         A hex-encoded signature of the canonical form of the metadata for ROLE.
 
+### Key objects ### {#file-formats-keys}
 
-All KEYs have the format:
+All KEY objects have the format:
 
 
 {
@@ -560,7 +563,7 @@ All KEYs have the format:
       ::
         A string denoting a public key signature system, such as "rsa", "ed25519", and "ecdsa-sha2-nistp256".
+        for="keytype">"ecdsa".
 
       : SCHEME
       ::
@@ -572,9 +575,21 @@ All KEYs have the format:
       ::
         A dictionary containing the public portion of the key.
 
-The reference implementation defines three signature schemes, although TUF
-is not restricted to any particular signature scheme, key type, or
-cryptographic library:
+The reference implementation defines three KEYTYPEs:
+"rsa", "ed25519", and
+"ecdsa"; and three signature SCHEMEs:
+"rsassa-pss-sha256", "ed25519", and
+"ecdsa-sha2-nistp256". These are documented below.
+
+TUF is not restricted to any particular signature SCHEMEs,
+KEYTYPEs, or cryptographic library. Adopters can define and use any
+particular KEYTYPE, signing SCHEME, and cryptographic library.
+
+Implementing the KEYTYPEs and SCHEMEs below is RECOMMENDED for
+all implementations, as this enables interoperability. Conversely,
+implementations SHOULD NOT implement the KEYTYPEs and SCHEMEs
+that are defined in a different manner than specified, so as to avoid confusion
+across implementations.
 
   : "rsassa-pss-sha256"
   ::
@@ -594,11 +609,6 @@ cryptographic library:
     [https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
     ](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm)
 
-We define three keytypes below: "rsa", "ed25519", and "ecdsa-sha2-nistp256", but adopters
-can define and use any particular keytype, signing scheme, and cryptographic
-library.
-
 The "rsa" format is:
 
 
@@ -631,11 +641,11 @@ The "ed25519" format is:
   ::
     64-byte hex encoded string.
 
-The "ecdsa-sha2-nistp256" format is:
+The "ecdsa" format is:
 
 
 {
-  "keytype" : "ecdsa-sha2-nistp256",
+  "keytype" : "ecdsa",
   "scheme" : "ecdsa-sha2-nistp256",
   "keyval" : {
     "public" : PUBLIC
@@ -647,6 +657,8 @@ The "ecdsa-sha2-nistp256" format is:
   ::
     PEM format and a string.
 
+### Date-time ### {#file-formats-date-time}
+
 Metadata date-time follows the ISO 8601 standard.  The expected
 format of the combined date and time string is "YYYY-MM-DDTHH:MM:SSZ".  Time is
 always in UTC, and the "Z" time zone designator is attached to indicate a
@@ -930,7 +942,7 @@ The "signed" portion of targets.json is as follows:
   "spec_version" : SPEC_VERSION,
   "version" : VERSION,
   "expires" : EXPIRES,
-  "targets" : TARGETS,
+  "targets" : TARGETS,
   ("delegations" : DELEGATIONS)
 }
 

@@ -964,8 +976,9 @@ as is described for the root.json file.
     definition](https://url.spec.whatwg.org/#path-relative-url-string) in the
     WHATWG URL specification.
 
-    It is allowed to have a TARGETS object with no TARGETPATH
-    elements.  This can be used to indicate that no target files are available.
+    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
   ::
@@ -1645,9 +1658,9 @@ when adding targets to the repository, or updating existing targets.
 
 ### Update targets metadata ### {#update-targets-metadata}
 
-1. Add the new (or update an existing) TARGETS object in the relevant
-   targets metadata (either the top-level targets metadata, or a delegated
-   targets metadata).
+1. Add the new (or update an existing) TARGETS object
+   in the relevant targets metadata (either the top-level targets metadata, or
+   a delegated targets metadata).
 2. Increment the VERSION number in the updated targets
    metadata.
 3. Sign the updated targets metadata with at least a THRESHOLD of keys