ITE-5: Replace signature wrapper with SSL signing spec

ITE/5/README.adoc

@@ -0,0 +1,186 @@
+= ITE-5: Replace signature envelope with SSL signing spec
+:source-highlighter: pygments
+:toc: preamble
+:toclevels: 2
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+:important-caption: :heavy_exclamation_mark:
+:caution-caption: :fire:
+:warning-caption: :warning:
+endif::[]
+
+.Metadata
+[cols="2"]
+|===
+| ITE
+| 5
+
+| Title
+| Replace signature envelope with SSL signing spec
+
+| Sponsor
+| link:https://github.com/santiagotorres[Santiago Torres]
+
+| Status
+| Draft 💬
+
+
+| Type
+| Standards
+
+| Created
+| 2020-09-28
+
+|===
+
+[[abstract]]
+== Abstract
+
+This link:https://github.com/in-toto/ITE[in-toto enhancement (ITE)] proposes
+switching to a new signature envelope in in-toto, namely the
+link:http://github.com/secure-systems-lab/signing-spec[SSL Signing Spec]. This
+has the following benefits over the current state:
+
+1. Avoids canonicalization for security reasons (i.e., to not parse untrusted input) 
+2. Reduces the possibility of misinterpretation of the payload. The serialized payload is encoded as a string and verified by the recipient before de-serializing.
+
+The old signature envelope would still be supported but deprecated, possibly to
+be removed in a future release.
+
+[[specification]]
+== Specification
+
+The specification adopted will be the SSL Signing Spec 0.1, as linked above. As
+such, we defer to that document to describe the specifics of signature
+generation and verification.
+
+The envelope's `payloadType` is `https://in-toto.io/schemas/LegacyJsonMessage`
+for both links and layouts (since they have a `_type` field.)
+
+The envelope's `payload` is the JSON serialization of the message, equivalent to
+the `signed` object in the current format.
+
+Once this ITE is accepted, we will change the website to redirect those URLs to
+point to documentation.
+
+[[pseudocode]]
+=== Pseudocode
+
+Implementations should process the authentication layer as follows:
+
+Inputs:
+
+* `file`: JSON-encoded link or layout
+* `recognizedSigners`: collection of (`name`, `publicKey`) pairs
+
+Outputs:
+
+* `message`: the signed message as an implementation-language-specific object
+* `signers`: set of recognized names that have signed the message
+
+Steps:
+
+* `envelope` := JsonDecode(`file`); raise error if the decoding fails
+* If `envelope.payload` exists (new-style envelope):
+ ** If `payloadType` != `https://in-toto.io/schemas/LegacyJsonMessage`,
+ raise error
+ ** `preauthEncoding` := PAE(UTF8(`envelope.payloadType`),
+ `envelope.payload`) as per signing-spec
+ ** `signers` := set of `name` for which Verify(`preauthEncoding`,
+ `signature.sig`, `publicKey`) succeeds, for all combinations of
+ (`signature`) in `envelope.signatures` and (`name`, `publicKey`) in
+ `recognizedSigners`
+ ** `message` := JsonDecode(`envelope.payload`)
+* Else if `envelope.signed` exists (old-style envelope):
+ ** `preauthEncoding` := CanonicalJsonEncode(`envelope.signed`)
+ ** `signers` := set of `name` for which Verify(`preauthEncoding`,
+ `signature.sig`, `publicKey`) succeeds, for all combinations of
+ (`signature`) in `envelope.signatures` and (`name`, `publicKey`) in
+ `recognizedSigners`
+ ** `message` := `envelope.signed`
+* Else, raise error
+* Raise error if `signers` is empty
+* Return `message` and `signers`
+
+
+[[motivation]]
+== Motivation
+
+The early motivations for in-toto to use the current envelope were to allow for
+our sister project, TUF, to transparently use the same crypto provider. The
+reasoning back then is that we would maximize code reuse, and allow for users
+of both solutions to easily integrate them.
+
+However, as time has shown, keeping these two separately-specified signature
+envelopes (i.e., one for TUF and one for in-toto) synchronized is rather difficult. As time
+passes, and due to the interactions in each community, the signature envelopes
+evolve to better fit their user-bases. Adopting a common source of truth (i.e.,
+a separate signature specification) should help increase cohesion between
+projects while maintaining the original goal of code-reuse and transparent
+integration.
+
+In addition, keeping the signature envelope specification *outside* of the
+current in-toto specification will also simplify the specification, which can
+now only focus on describing in-toto specifics, rather than cryptographic
+building blocks.
+
+[[reasoning]]
+== Reasoning
+
+Our goal was to adopt a signature envelope that is as simple and foolproof as
+possible. Alternatives such as link:https://tools.ietf.org/html/rfc7515[JWS] are
+extremely complex and error-prone, while others such as
+link:https://github.com/paragonie/paseto/blob/master/docs/01-Protocol-Versions/Version2.md#sig[PASETO]
+are overly specific. (Both are also JSON-specific.) We believe the SSL signing
+spec strikes the right balance of simplicity, usefulness, and security. 
+
+Further, the SSL signing spec is a "natural evolution" of the current signature
+envelope, which was defined in both the TUF and in-toto specifications. As such,
+it allows for a transparent upgrade via their cryptographic provider,
+link:https://github.com/secure-systems-lab/securesystemslib[securesystemslib].
+
+Further information on the reasoning behind the envelope's specifics is provided in the link:https://github.com/secure-systems-lab/signing-spec[signing specification] repository
+
+[[backwards-compatibility]]
+== Backwards Compatibility
+
+Implementations should continue to support old-style envelope as well as
+new-style SSL Signing Spec envelopes, as defined in the
+link:#pseudocode[pseudocode] above.
+
+[[security]]
+== Security
+
+At first sight this proposal is central to security, yet the actual
+contribution is to allow for a signature provider to be disaggregated from the
+specification. As such, no supply-chain security properties are removed from
+the system through this ITE.
+
+The adoption of SSL signing spec slightly improves the security stance of
+implementations because they are no longer parsing untrusted input.
+
+[[infrastructure-requirements]]
+== Infrastructure Requirements
+
+Since this is a change in the metadata format, no infrastructure requirements
+exist.
+
+
+[[prototype-implementation]]
+== Prototype Implementation
+
+None yet.
+
+[[testing]]
+== Testing
+
+The test-suite should include loading/generating both new-style SSL signing spec
+metadata as well old-style metadata.
+
+[[references]]
+== References
+
+* link:http://gibson042.github.io/canonicaljson-spec/[Canonical JSON]
+* link:https://tools.ietf.org/html/rfc7515[JWS]
+* link:https://github.com/paragonie/paseto/blob/master/docs/01-Protocol-Versions/Version2.md#sig[PASETO]

README.md

@@ -9,6 +9,7 @@
 
 * [ITE-2: A general overview of combining TUF and in-toto to build compromise-resilient CI/CD](ITE/2/README.adoc)
 * [ITE-3: Real-world example of combining TUF and in-toto for packaging Datadog Agent integrations](ITE/3/README.adoc)
+* [ITE-5: Replace signature envelope with SSL signing spec](ITE/5/README.adoc)
 
 ## License