From 052ecebf36be4ffb4e498aa64ed2c9af463fdb90 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Tue, 8 Dec 2020 15:51:59 -0500 Subject: [PATCH 1/5] Reformat to follow Markdown style guide --- specification.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/specification.md b/specification.md index 87f7790..4247a6f 100644 --- a/specification.md +++ b/specification.md @@ -1,6 +1,7 @@ # $signing_spec -A signature scheme for software supply chain metadata that avoids canonicalization +A signature scheme for software supply chain metadata that avoids +canonicalization November 25, 2020 @@ -271,8 +272,8 @@ Rationales for specific decisions: The [current signature format](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#42-file-formats-general-principles) -used by TUF and in-toto has a BODY that is a regular JSON object and a signature over the -[Canonical JSON] serialization of BODY. +used by TUF and in-toto has a BODY that is a regular JSON object and a signature +over the [Canonical JSON] serialization of BODY. ```json { @@ -351,9 +352,9 @@ Signed wrapper: ## References -- [Canonical JSON] -- [JWS] -- [PASETO] +- [Canonical JSON] +- [JWS] +- [PASETO] [Canonical JSON]: http://wiki.laptop.org/go/Canonical_JSON [JWS]: https://tools.ietf.org/html/rfc7515 From 6918d401aee7b10998a3b9c07ff2f663781712f1 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Tue, 8 Dec 2020 15:52:59 -0500 Subject: [PATCH 2/5] Remove []'s from PAE() function. Originally, the document used `PAE([...])` since the PASETO PAE takes a single array of strings as an argument. But there is no need for this documentation compatibility, and the extra []'s just add visual clutter. It is clearer to remove them. --- specification.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification.md b/specification.md index 4247a6f..2551e90 100644 --- a/specification.md +++ b/specification.md @@ -34,7 +34,7 @@ The signature format is a JSON message of the following form: "payloadType": "", "signatures": [{ …, - "sig": "" + "sig": "" }, …] } ``` @@ -60,7 +60,7 @@ where: where parameters `type` and `body` are byte sequences: ```none - PAE([type, body]) := le64(2) || le64(len(type)) || type || le64(len(body)) || body + PAE(type, body) := le64(2) || le64(len(type)) || type || le64(len(body)) || body le64(n) := 64-bit little-endian encoding of `n`, where 0 <= n < 2^63 ``` @@ -80,7 +80,7 @@ where: To sign: - Serialize BODY according to PAYLOAD_TYPE. Call the result SERIALIZED_BODY. -- Sign PAE([UTF8(PAYLOAD_TYPE), SERIALIZED_BODY]), base64-encode the result, +- Sign PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY), base64-encode the result, and store it in `sig`. - Base64-encode SERIALIZED_BODY and store it in `payload`. - Store PAYLOAD_TYPE in `payloadType`. @@ -89,7 +89,7 @@ To verify: - Base64-decode `payload`; call this SERIALIZED_BODY. Reject if the decoding fails. -- Base64-decode `sig` and verify PAE([UTF8(PAYLOAD_TYPE), SERIALIZED_BODY]). +- Base64-decode `sig` and verify PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY). Reject if either the decoding or the signature verification fails. - Parse SERIALIZED_BODY according to PAYLOAD_TYPE. Reject if the parsing fails. From 3326187e87e0e25bbca33f9eb87f619e1180c4d0 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Tue, 8 Dec 2020 17:07:49 -0500 Subject: [PATCH 3/5] Clarify out-of-band negotation. Clarify that the signer and verifier should agree on payloadType and whether backwards compatibility should be supported. --- specification.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specification.md b/specification.md index 2551e90..107c279 100644 --- a/specification.md +++ b/specification.md @@ -77,6 +77,11 @@ where: ### Steps +Out of band: + +- Agree on a PAYLOAD_TYPE and cryptographic details. +- Decide if [backwards compatible signature] mode should be allowed. + To sign: - Serialize BODY according to PAYLOAD_TYPE. Call the result SERIALIZED_BODY. @@ -91,6 +96,7 @@ To verify: fails. - Base64-decode `sig` and verify PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY). Reject if either the decoding or the signature verification fails. +- Reject if PAYLOAD_TYPE is not a supported type. - Parse SERIALIZED_BODY according to PAYLOAD_TYPE. Reject if the parsing fails. @@ -356,6 +362,7 @@ Signed wrapper: - [JWS] - [PASETO] +[backwards compatible signature]: #backwards-compatible-signatures [Canonical JSON]: http://wiki.laptop.org/go/Canonical_JSON [JWS]: https://tools.ietf.org/html/rfc7515 [PASETO]: https://github.com/paragonie/paseto/blob/master/docs/01-Protocol-Versions/Version2.md#sig From dfbd1de64ced7f828158297f7b0d474b6225cb2e Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Tue, 8 Dec 2020 17:23:10 -0500 Subject: [PATCH 4/5] Minor rewording on backwards compatibility --- specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification.md b/specification.md index 107c279..78a7b76 100644 --- a/specification.md +++ b/specification.md @@ -272,12 +272,12 @@ Rationales for specific decisions: 2. It would incur double base64 encoding overhead for non-JSON payloads. 3. It is more complex than PAE. -## Backwards Compatibility +## Backwards compatibility with existing TUF and in-toto signatures ### Current format The -[current signature format](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#42-file-formats-general-principles) +[old signature format](https://github.com/in-toto/docs/blob/master/in-toto-spec.md#42-file-formats-general-principles) used by TUF and in-toto has a BODY that is a regular JSON object and a signature over the [Canonical JSON] serialization of BODY. From f03d543034874b9918cc33285281b596c9bd06fe Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Tue, 8 Dec 2020 17:49:19 -0500 Subject: [PATCH 5/5] Replace "BODY" with "the message". --- specification.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/specification.md b/specification.md index 78a7b76..e6c0d69 100644 --- a/specification.md +++ b/specification.md @@ -84,9 +84,10 @@ Out of band: To sign: -- Serialize BODY according to PAYLOAD_TYPE. Call the result SERIALIZED_BODY. -- Sign PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY), base64-encode the result, - and store it in `sig`. +- Serialize the message according to PAYLOAD_TYPE. Call the result + SERIALIZED_BODY. +- Sign PAE(UTF8(PAYLOAD_TYPE), SERIALIZED_BODY), base64-encode the result, and + store it in `sig`. - Base64-encode SERIALIZED_BODY and store it in `payload`. - Store PAYLOAD_TYPE in `payloadType`. @@ -317,7 +318,7 @@ To convert a backwards compatible signature to the old format: See [reference implementation](reference_implementation.ipynb). Here is an example. -BODY: +SERIALIZED_BODY: ```none hello world