Resolve comments from pull request #23.

- Fix typos.
- Add TODO to update "current" to "legacy" whenever TUF/in-toto switch
  to this.
- Add "Why not existing TUF/in-toto" to README.
- Clean up references to the JSON envelope in protocol.md.

Author: MarkLodato

README.md

@@ -30,10 +30,16 @@ Out of scope (for now at least):
 *   Why not [JOSE/JWS/JWT](https://jwt.io)? JSON-specific, too complicated, too
     easy to mess up.
 *   Why not [PASETO](https://paseto.io)? JSON-specific, too opinionated.
+*   Why not the legacy TUF/in-toto signature scheme? JSON-specific, relies on
+    canonicalization.
 
 See [Background](background.md) for further motivation.
 
 ## Who uses it?
 
+<!-- Reminder: once in-toto and TUF switch to this new format, update the rest
+of the docs that currently reference the old format as "current", "existing",
+etc. -->
+
 *   [in-toto](https://in-toto.io) (pending [ITE-5](https://github.com/in-toto/ITE/pull/13))
 *   [TUF](https://theupdateframework.io) (pending)

background.md

@@ -11,8 +11,8 @@ and [in-toto].
 
 There is no other simple, foolproof signature scheme that we are aware of.
 
-*   Raw signatures are too fragle. Every public key must be used for exactly one
-    purpose over exactly one message type, lest the system be vulnerable to
+*   Raw signatures are too fragile. Every public key must be used for exactly
+    one purpose over exactly one message type, lest the system be vulnerable to
     [confusion attacks](#motivation). In many cases, this results in a difficult
     key management problem.
 
@@ -78,7 +78,7 @@ signed, which the verifier verifies before parsing. This is what is done in
 
 Second, the scheme does not include an authenticated "context" indicator to
 ensure that the signer and verifier interpret the payload in the same exact way.
-For example, if in-toto were extended to support CBOR and Protobuf encoding, the
+For example, if in-toto were extended to support CBOR and protobuf encoding, the
 signer could get a CI/CD system to produce a CBOR message saying X and then a
 verifier to interpret it as a protobuf message saying Y. While we don't know of
 an exploitable attack on in-toto or TUF today, potential changes could introduce

envelope.md

@@ -58,7 +58,7 @@ The standard envelope is JSON message with an explicit `payloadType`.
 Optionally, applications may encode the signed message in other methods without
 invalidating the signature:
 
--   An encoding other than JSON, such as CBOR or Protobuf.
+-   An encoding other than JSON, such as CBOR or protobuf.
 -   Use a default `payloadType` if omitted and/or code `payloadType` as a
     shorter string or enum.
 

protocol.md

@@ -66,15 +66,14 @@ To sign:
     SERIALIZED_BODY.
 -   Sign PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY). Call the result SIGNATURE.
 -   Optionally, compute a KEYID.
--   Encode and transmit SERIALIZED_BODY, PAYLOAD_TYPE, SIGNATURE, and KEYID.
-    -   In the recommended [JSON envelope](envelope.md), this is
-        `{"payload": "Base64(SERIALIZED_BODY)", "payloadType": "PAYLOAD_TYPE",
-        "signatures": [{"keyid": "KEYID", "sig": "Base64(SIGNATURE)"}]}`.
+-   Encode and transmit SERIALIZED_BODY, PAYLOAD_TYPE, SIGNATURE, and KEYID,
+    preferably using the recommended [JSON envelope](envelope.md).
 
 To verify:
 
--   Receive and decode SERIALIZED_BODY, PAYLOAD_TYPE, SIGNATURE, and KEYID.
-    Reject if decoding fails.
+-   Receive and decode SERIALIZED_BODY, PAYLOAD_TYPE, SIGNATURE, and KEYID, such
+    as from the recommended [JSON envelope](envelope.md). Reject if decoding
+    fails.
 -   Optionally, filter acceptable public keys by KEYID.
 -   Verify SIGNATURE against PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY). Reject if
     the verification fails.