Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify current state of key formats in the spec #272

Merged
merged 5 commits into from
May 15, 2023
Merged

Clarify current state of key formats in the spec #272

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d9cbcac
Update keytype for ecdsa keys and clarify references
joshuagl Mar 1, 2023
0c723c3
Fix bikeshed link errors
joshuagl Mar 1, 2023
4220381
Add more navigation headers for file format details
joshuagl Mar 1, 2023
74ecb27
Bump date and minor version
joshuagl Mar 2, 2023
de6b164
Make object format, key format, and date-time subsections
joshuagl Mar 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 33 additions & 20 deletions tuf-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
</pre>

Note: We strive to make the specification easy to implement, so if you come
Expand Down Expand Up @@ -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:

<pre highlight="json">
Expand Down Expand Up @@ -545,8 +547,9 @@ All signed metadata objects have the format:
::
A hex-encoded signature of the canonical form of the metadata for <a for="role">ROLE</a>.

### Key objects ### {#file-formats-keys}

All <dfn>KEY</dfn>s have the format:
All <dfn>KEY</dfn> objects have the format:

<pre highlight="json">
{
Expand All @@ -560,7 +563,7 @@ All <dfn>KEY</dfn>s have the format:
::
A string denoting a public key signature system, such as <a
for="keytype">"rsa"</a>, <a for="keytype">"ed25519"</a>, and <a
for="keytype">"ecdsa-sha2-nistp256"</a>.
for="keytype">"ecdsa"</a>.

: <dfn>SCHEME</dfn>
::
Expand All @@ -572,9 +575,21 @@ All <dfn>KEY</dfn>s 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 <a>KEYTYPE</a>s:
<a for="keytype">"rsa"</a>, <a for="keytype">"ed25519"</a>, and
<a for="keytype">"ecdsa"</a>; and three signature <a>SCHEME</a>s:
<a for="scheme">"rsassa-pss-sha256"</a>, <a for="scheme">"ed25519"</a>, and
<a for="scheme">"ecdsa-sha2-nistp256"</a>. These are documented below.

TUF is not restricted to any particular signature <a>SCHEME</a>s,
<a>KEYTYPE</a>s, or cryptographic library. Adopters can define and use any
particular <a>KEYTYPE</a>, signing <a>SCHEME</a>, and cryptographic library.

Implementing the <a>KEYTYPE</a>s and <a>SCHEME</a>s below is RECOMMENDED for
all implementations, as this enables interoperability. Conversely,
implementations SHOULD NOT implement the <a>KEYTYPE</a>s and <a>SCHEME</a>s
that are defined in a different manner than specified, so as to avoid confusion
across implementations.

: <dfn for="scheme">"rsassa-pss-sha256"</dfn>
::
Expand All @@ -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: <a for="keytype">"rsa"</a>, <a
for="keytype">"ed25519"</a>, and <a for="keytype">"ecdsa-sha2-nistp256"</a>, but adopters
can define and use any particular keytype, signing scheme, and cryptographic
library.

The <dfn for="keytype">"rsa"</dfn> format is:

<pre highlight="json">
Expand Down Expand Up @@ -631,11 +641,11 @@ The <dfn for="keytype">"ed25519"</dfn> format is:
::
64-byte hex encoded string.

The <dfn for="keytype">"ecdsa-sha2-nistp256"</dfn> format is:
The <dfn for="keytype">"ecdsa"</dfn> format is:

<pre highlight="json">
{
"keytype" : <a for="keytype">"ecdsa-sha2-nistp256"</a>,
"keytype" : <a for="keytype">"ecdsa"</a>,
"scheme" : <a for="scheme">"ecdsa-sha2-nistp256"</a>,
"keyval" : {
"public" : <a for="keyval-ecdsa">PUBLIC</a>
Expand All @@ -647,6 +657,8 @@ The <dfn for="keytype">"ecdsa-sha2-nistp256"</dfn> format is:
::
PEM format and a string.

### Date-time ### {#file-formats-date-time}

Metadata <dfn>date-time</dfn> 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
Expand Down Expand Up @@ -930,7 +942,7 @@ The "signed" portion of <dfn>targets.json</dfn> is as follows:
"spec_version" : <a>SPEC_VERSION</a>,
"version" : <a for="role">VERSION</a>,
"expires" : <a>EXPIRES</a>,
"targets" : <a>TARGETS</a>,
"targets" : <a for="targets-obj">TARGETS</a>,
("delegations" : <a>DELEGATIONS</a>)
}
</pre>
Expand Down Expand Up @@ -964,8 +976,9 @@ as is described for the <a>root.json</a> file.
definition](https://url.spec.whatwg.org/#path-relative-url-string) in the
WHATWG URL specification.

It is allowed to have a <a>TARGETS</a> object with no <a>TARGETPATH</a>
elements. This can be used to indicate that no target files are available.
It is allowed to have a <a for="targets-obj">TARGETS</a> object with no
<a>TARGETPATH</a> elements. This can be used to indicate that no target
files are available.

: <dfn for="targets-obj">LENGTH</dfn>
::
Expand Down Expand Up @@ -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) <a>TARGETS</a> 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) <a for="targets-obj">TARGETS</a> object
in the relevant targets metadata (either the top-level targets metadata, or
a delegated targets metadata).
2. Increment the <a for="role">VERSION</a> number in the updated targets
metadata.
3. Sign the updated targets metadata with at least a <a>THRESHOLD</a> of keys
Expand Down