Merge pull request #4 from adityasaky/adityasaky-ite-3

ITE-3: Early pass at addressing some review comments

ITE/3/README.adoc

@@ -17,7 +17,7 @@ endif::[]
 | 3
 
 | Title
-| in-toto Enhancement format
+| Real-world example of combining TUF and in-toto for packaging Datadog Agent integrations
 
 | Sponsor
 | link:https://github.com/trishankatdatadog[Trishank Karthik Kuppusamy]
@@ -109,7 +109,10 @@ source code that was never released by Datadog developers.
 The root layout uses (2, 3) offline keys, and its metadata expires in 1 year.
 (See this
 https://dd-integrations-core-wheels-build-stable.datadoghq.com/targets/in-toto-metadata/root.layout[example]
-root layout metadata file.)
+root layout metadata file.) Using a threshold of two keys to sign the root
+provides the benefits of the two-man rule developed by the US Air Force, while
+a third key in the pool of valid keys allows for redundancies in situations
+where a compromised key must be revoked and replaced.
 
 (The root layout also tracks previously built Python metadata and wheels, as
 well as their corresponding in-toto link metadata files, as they move through
@@ -134,8 +137,9 @@ metadata and wheels for integrations beginning with the letter "`b`" to
 the "`wheels-signer-b`" role, and so on until it finishes sending all Python metadata and
 wheels for integrations beginning with the letter "`z`" to the
 "`wheels-signer-z`" role. Thus, there are 26 of these roles, all of which 
-use (2, 3) offline keys, and do not directly sign for any Python metadata
-or wheel. Metadata expires for these wheels-signer roles expire in 1 year. The following is an excerpt of the
+use (2, 3) offline keys for the same reasons as the root layout, and do not
+directly sign for any Python metadata or wheel. Metadata expires for these
+wheels-signer roles expire in 1 year. The following is an excerpt of the
 https://dd-integrations-core-wheels-build-stable.datadoghq.com/metadata.staged/wheels-signer.json[example]
 metadata file:
 
@@ -204,7 +208,8 @@ In particular, each directory containing in-toto link metadata
 for one or more associated wheel is named directly using the SHA-256
 hexadecimal digest of the "`tag`" link metadata file associated with
 these wheels. Each role uses (1,1) online keys, does not delegate any
-Python metadata or wheel, and its metadata expires in 1 week. The following is
+Python metadata or wheel, and its metadata expires in 1 week, which is
+the maximum lifetime allowed for a release of a wheel. The following is
 an excerpt of the
 https://dd-integrations-core-wheels-build-stable.datadoghq.com/metadata.staged/wheels-signer-a.json[example]
 metadata file:
@@ -307,7 +312,8 @@ Each "`in-toto-metadata-singer-[0-f]`" role signs targets metadata about
 a certain subset of in-toto-link metadata files inside directories
 beginning with a particular letter. Each role uses (1,1) online keys,
 does not delegate any in-toto link metadata file, and its metadata
-expires in 1 week. The following is an excerpt of the
+expires in 1 week, which is again based on the release lifetime. The
+following is an excerpt of the
 https://dd-integrations-core-wheels-build-stable.datadoghq.com/metadata.staged/in-toto-metadata-signer-3.json[example]
 metadata file:
 
@@ -352,7 +358,8 @@ makes a terminating delegation of all Python metadata and wheels to the
 "`wheels-signer`" role. Finally, it makes a terminating delegation of
 all in-toto link metadata to the "`in-toto-metadata-signer`" role. It
 uses a different set of (2, 3) offline keys from the in-toto root
-layout, but its metadata also expires in 1 year. In addition, it shares
+layout to maintain the principle of separation of duties, but its
+metadata also expires in 1 year. In addition, it shares
 its keys with the "`wheels-signer`" and "`in-toto-metadata-signer`"
 roles. The following is an excerpt of the
 https://dd-integrations-core-wheels-build-stable.datadoghq.com/metadata.staged/targets.json[example]
@@ -443,7 +450,10 @@ metadata files.)
 
 The root role uses a different set of (2, 3) offline keys from both the
 in-toto root layout and the targets role, and its metadata expires in 1
-year. (See this
+year. Using different sets of (2, 3) offline keys provide the benefits
+of the two-man rule while also clearly separating the duties of the root
+role, the targets role, and the in-toto root layout.
+(See this
 https://dd-integrations-core-wheels-build-stable.datadoghq.com/metadata.staged/root.json[example]
 the root metadata file.) All TUF metadata and targets are written using
 https://github.com/theupdateframework/specification/blob/master/tuf-spec.md#7-consistent-snapshots[consistent