Use a simpler ASCII-based PAE (#27)

MarkLodato · MarkLodato · commit 93903bf3ca86 · 2021-06-04T13:11:39.000-04:00
The previous PAE required binary encoding, which can be tricky in some
langauges. The new PAE is pure ASCII so it can be implemented very
easily in almost any language.
diff --git a/implementation/signing_spec.py b/implementation/signing_spec.py
@@ -6,7 +6,7 @@
 The following example requires `pip3 install pycryptodome` and uses ecdsa.py in
 the same directory as this file.
 
->>> import binascii, os, sys, textwrap
+>>> import os, sys
 >>> from pprint import pprint
 >>> sys.path.insert(0, os.path.dirname(__file__))
 >>> import ecdsa
@@ -26,7 +26,7 @@
 >>> pprint(json.loads(signature_json))
 {'payload': 'aGVsbG8gd29ybGQ=',
  'payloadType': 'http://example.com/HelloWorld',
- 'signatures': [{'sig': 'Cc3RkvYsLhlaFVd+d6FPx4ZClhqW4ZT0rnCYAfv6/ckoGdwT7g/blWNpOBuL/tZhRiVFaglOGTU8GEjm4aEaNA=='}]}
+ 'signatures': [{'sig': 'A3JqsQGtVsJ2O2xqrI5IcnXip5GToJ3F+FnZ+O88SjtR6rDAajabZKciJTfUiHqJPcIAriEGAHTVeCUjW2JIZA=='}]}
 
 Verification example:
 
@@ -36,14 +36,8 @@
 
 PAE:
 
->>> def print_hex(b: bytes):
-...   octets = ' '.join(textwrap.wrap(binascii.hexlify(b).decode('utf-8'), 2))
-...   print(*textwrap.wrap(octets, 48), sep='\n')
->>> print_hex(PAE(payloadType, payload))
-02 00 00 00 00 00 00 00 1d 00 00 00 00 00 00 00
-68 74 74 70 3a 2f 2f 65 78 61 6d 70 6c 65 2e 63
-6f 6d 2f 48 65 6c 6c 6f 57 6f 72 6c 64 0b 00 00
-00 00 00 00 00 68 65 6c 6c 6f 20 77 6f 72 6c 64
+>>> PAE(payloadType, payload)
+b'DSSEv1 29 http://example.com/HelloWorld 11 hello world'
 """
 
 import base64, binascii, dataclasses, json, struct
@@ -88,12 +82,9 @@ def b64dec(m: str) -> bytes:
 
 
 def PAE(payloadType: str, payload: bytes) -> bytes:
-    return b''.join([
-        struct.pack('<Q', 2),
-        struct.pack('<Q', len(payloadType)),
-        payloadType.encode('utf-8'),
-        struct.pack('<Q', len(payload)), payload
-    ])
+    return b'DSSEv1 %d %b %d %b' % (
+            len(payloadType), payloadType.encode('utf-8'),
+            len(payload), payload)
 
 
 def Sign(payloadType: str, payload: bytes, signer: Signer) -> str:
diff --git a/protocol.md b/protocol.md
@@ -53,13 +53,12 @@ KEYID           | string | No       | No
 
 Functions:
 
-*   PAE() is the
-    [PASETO Pre-Authentication Encoding](https://github.com/paragonie/paseto/blob/master/docs/01-Protocol-Versions/Common.md#authentication-padding),
-    where parameters `type` and `body` are byte sequences:
+*   PAE() is the "Pre-Authentication Encoding", where parameters `type` and
+    `body` are byte sequences:
 
-    ```none
-    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
+    ```python
+    PAE(type, body) := "DSSEv1 <len(type)> <type> <len(body)> <body>"
+    len(s) := ASCII decimal encoding of the byte length of s, with no leading zeros
     ```
 
 *   Sign() is an arbitrary digital signature format. Details are agreed upon
@@ -102,7 +101,7 @@ either, and verifiers **MUST** accept either.
 
 ## Test Vectors
 
-See [reference implementation](reference_implementation.ipynb). Here is an
+See [reference implementation](implementation/signing_spec.py). Here is an
 example.
 
 SERIALIZED_BODY:
@@ -120,10 +119,7 @@ http://example.com/HelloWorld
 PAE:
 
 ```none
-02 00 00 00 00 00 00 00 1d 00 00 00 00 00 00 00
-68 74 74 70 3a 2f 2f 65 78 61 6d 70 6c 65 2e 63
-6f 6d 2f 48 65 6c 6c 6f 57 6f 72 6c 64 0b 00 00
-00 00 00 00 00 68 65 6c 6c 6f 20 77 6f 72 6c 64
+DSSEv1 29 http://example.com/HelloWorld 11 hello world
 ```
 
 Cryptographic keys:
@@ -141,7 +137,7 @@ Result (using the recommended [JSON envelope](envelope.md)):
 ```json
 {"payload": "aGVsbG8gd29ybGQ=",
  "payloadType": "http://example.com/HelloWorld",
- "signatures": [{"sig": "y7BK8Mm8Mr4gxk4+G9X3BD1iBc/vVVuJuV4ubmsEK4m/8MhQOOS26ejx+weIjyAx8VjYoZRPpoXSNjHEzdE7nQ=="}]}
+ "signatures": [{"sig": "A3JqsQGtVsJ2O2xqrI5IcnXip5GToJ3F+FnZ+O88SjtR6rDAajabZKciJTfUiHqJPcIAriEGAHTVeCUjW2JIZA=="}]}
 ```
 
 [Canonical JSON]: http://wiki.laptop.org/go/Canonical_JSON
