Merge pull request #26 from MarkLodato/opaque-type

Relax URI requirement on payloadType

Author: mnm678

background.md

@@ -119,17 +119,6 @@ Rationales for specific decisions:
         payloadType and payload. PAE is already documented and good enough. No
         need to reinvent the wheel.
 
--   Why use a URI for payloadType rather than
-    [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml)
-    (a.k.a. MIME type)?
-
-    -   Because Media Type only indicates how to parse but does not indicate
-        purpose, schema, or versioning. If it were just "application/json", for
-        example, then every application would need to impose some "type" field
-        within the payload, lest we have similar vulnerabilities as if
-        payloadType were not signed.
-    -   Also, URIs don't need to be registered while Media Types do.
-
 -   Why not stay backwards compatible by requiring the payload to always be JSON
     with a "_type" field? Then if you want a non-JSON payload, you could simply
     have a field that contains the real payload, e.g. `{"_type":"my-thing",

protocol.md

@@ -18,19 +18,35 @@ SIGNATURE = Sign(PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY))
 
 Parameters:
 
-*   SERIALIZED_BODY is the byte sequence to be signed.
-
-*   PAYLOAD_TYPE is an authenticated URI indicating how to interpret
-    SERIALIZED_BODY. It encompasses the content type (JSON, Canonical-JSON,
-    CBOR, etc.), the purpose, and the schema version of the payload. This
-    obviates the need for the `_type` field within [in-toto]/[TUF] payloads.
-    This URI does not need to be resolved to a remote resource, nor does such a
-    resource need to be fetched. Examples: `https://in-toto.io/Link/v1.0`,
-    `https://in-toto.io/Layout/v1.0`,
-    `https://theupdateframework.com/Root/v1.0.5`.
-
-*   KEYID is an optional, unauthenticated hint indicating what key and algorithm
-    was used to sign the message. As with Sign(), details are agreed upon
+Name            | Type   | Required | Authenticated
+--------------- | ------ | -------- | -------------
+SERIALIZED_BODY | bytes  | Yes      | Yes
+PAYLOAD_TYPE    | string | Yes      | Yes
+KEYID           | string | No       | No
+
+*   SERIALIZED_BODY: Byte sequence to be signed.
+
+*   PAYLOAD_TYPE: Opaque, case-sensitive string that uniquely and unambiguously
+    identifies how to interpret `payload`. This includes both the encoding
+    (JSON, CBOR, etc.) as well as the meaning/schema. To prevent collisions, the
+    value SHOULD be either:
+
+    *   [URI](https://tools.ietf.org/html/rfc3986) (recommended)
+        *   Example: `https://in-toto.io/Statement/v1-json`.
+        *   SHOULD resolve to a human-readable description but MAY be
+            unresolvable.
+        *   SHOULD be case-normalized (section 6.2.2.1)
+    *   [Media Type](https://www.iana.org/assignments/media-types/), a.k.a. MIME
+        type or Content Type
+        *   Example: `application/vnd.in-toto.statement.v1+json`.
+        *   IMPORTANT: SHOULD NOT be a generic type that only represents
+            encoding but not schema. For example, `application/json` is almost
+            always WRONG. Instead, invent a media type specific for your
+            application in the `application/vnd` namespace.
+        *   SHOULD be lowercase.
+
+*   KEYID: Optional, unauthenticated hint indicating what key and algorithm was
+    used to sign the message. As with Sign(), details are agreed upon
     out-of-band by the signer and verifier. It **MUST NOT** be used for security
     decisions; it may only be used to narrow the selection of possible keys to
     try.