From d9cbcacba40466213c2ddb9b2caa09b299c119c7 Mon Sep 17 00:00:00 2001 From: Joshua Lock Date: Wed, 1 Mar 2023 17:59:58 +0000 Subject: [PATCH 1/5] Update keytype for ecdsa keys and clarify references We claim that the spec is just documenting the signature _schemes_ from the reference implementation, but that we define three _keytypes_ within the spec. This change first updates the _keytypes_ to match the reference implementation (we have defaulted to a generic "ecdsa" keytype since https://github.com/secure-systems-lab/securesystemslib/pull/267). Further, we update the specification to clarify that within we are documenting the keytypes and schemes from the reference implementation, and that we recommend implementing these keytypes and schemes as specified. Signed-off-by: Joshua Lock --- tuf-spec.md | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/tuf-spec.md b/tuf-spec.md index 0bf40a4..03d3c80 100644 --- a/tuf-spec.md +++ b/tuf-spec.md @@ -560,7 +560,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 +572,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 +606,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 +638,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

From 0c723c39acc8c6bbc2d2912fabf8a64c5caf1828 Mon Sep 17 00:00:00 2001
From: Joshua Lock 
Date: Wed, 1 Mar 2023 18:00:31 +0000
Subject: [PATCH 2/5] Fix bikeshed link errors

Signed-off-by: Joshua Lock 
---
 tuf-spec.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/tuf-spec.md b/tuf-spec.md
index 03d3c80..4dcde6c 100644
--- a/tuf-spec.md
+++ b/tuf-spec.md
@@ -937,7 +937,7 @@ The "signed" portion of targets.json is as follows:
   "spec_version" : SPEC_VERSION,
   "version" : VERSION,
   "expires" : EXPIRES,
-  "targets" : TARGETS,
+  "targets" : TARGETS,
   ("delegations" : DELEGATIONS)
 }
 

@@ -971,8 +971,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
   ::
@@ -1652,9 +1653,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

From 4220381e92c07ea0a4c0e804a6d8f5cdfc1356d3 Mon Sep 17 00:00:00 2001
From: Joshua Lock 
Date: Wed, 1 Mar 2023 19:07:34 +0000
Subject: [PATCH 3/5] Add more navigation headers for file format details

Make it easier to find key formats and, more importantly because it's
often missed, date-time recommendations.

Signed-off-by: Joshua Lock 
---
 tuf-spec.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tuf-spec.md b/tuf-spec.md
index 4dcde6c..4dbc204 100644
--- a/tuf-spec.md
+++ b/tuf-spec.md
@@ -545,8 +545,9 @@ All signed metadata objects have the format:
       ::
         A hex-encoded signature of the canonical form of the metadata for ROLE.
 
+## File formats: keys ## {#file-formats-keys}
 
-All KEYs have the format:
+All KEY objects have the format:
 
 
 {
@@ -654,6 +655,8 @@ The "ecdsa" format is:
   ::
     PEM format and a string.
 
+## File formats: 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

From 74ecb2720552e0a39871dd101f21144fc470800b Mon Sep 17 00:00:00 2001
From: Joshua Lock 
Date: Thu, 2 Mar 2023 11:34:24 +0000
Subject: [PATCH 4/5] Bump date and minor version

Signed-off-by: Joshua Lock 
---
 tuf-spec.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tuf-spec.md b/tuf-spec.md
index 4dbc204..83dd003 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

From de6b164b0bba0af3f6c5eada646ca5a092723dfa Mon Sep 17 00:00:00 2001
From: Joshua Lock 
Date: Wed, 15 Mar 2023 11:51:02 +0000
Subject: [PATCH 5/5] Make object format, key format, and date-time subsections

These all form part of the general principles of the pedagogical file
format, so move them to be one level heading lower.

Signed-off-by: Joshua Lock 
---
 tuf-spec.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/tuf-spec.md b/tuf-spec.md
index 83dd003..05ee4d2 100644
--- a/tuf-spec.md
+++ b/tuf-spec.md
@@ -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,7 +547,7 @@ All signed metadata objects have the format:
       ::
         A hex-encoded signature of the canonical form of the metadata for ROLE.
 
-## File formats: keys ## {#file-formats-keys}
+### Key objects ### {#file-formats-keys}
 
 All KEY objects have the format:
 
@@ -655,7 +657,7 @@ The "ecdsa" format is:
   ::
     PEM format and a string.
 
-## File formats: date-time ## {#file-formats-date-time}
+### 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