Skip to content

Commit 261fb6d

Browse files
committed
Reword section on canonical JSON format
1 parent ab711be commit 261fb6d

File tree

1 file changed

+5
-8
lines changed

1 file changed

+5
-8
lines changed

index.html

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -813,7 +813,7 @@ <h3 id="message-format">Message format</h3>
813813
<h4 id="signature">Signature</h4>
814814
<div>
815815
<p>All messages in a feed are signed by that feed’s long-term secret key. This enables recipients to verify that a message was really posted by a particular identity and not tampered with as it gets gossiped and replicated throughout the Scuttlebutt network.</p>
816-
<p>Before signing a message it must be formatted as JSON as shown above. The formatting rules are:</p>
816+
<p>Before signing a message it must be serialized according to a specific canonical JSON format. This means for any given message there is exactly one way to serialize it as a sequence of bytes, which is necessary for signature verification to work. The reference implementation verifies that all messages it receives are in the canonical format and rejects messages that aren’t.</p>
817817
</div>
818818
<aside class="impl">
819819
<img class="icon" src="img/impl.png"/>
@@ -824,21 +824,18 @@ <h5>Implementations</h5>
824824
<div class="lang">Py</div>
825825
<div class="vs"><a href="https://github.com/pferreir/pyssb/blob/master/ssb/feed/models.py">models.py</a></div>
826826
</aside>
827+
<p>The canonical format is defined by the <em>ECMA-262 6<sup>th</sup> Edition</em> section <em><a href="https://www.ecma-international.org/ecma-262/6.0/#sec-json.stringify">JSON.stringify</a></em>. For an example, see how the above message is formatted.</p>
828+
<p>In brief, the rules are:</p>
827829
<ul>
828830
<li>Two spaces for indentation.</li>
829831
<li>Dictionary entries and list elements each on their own line.</li>
830832
<li>Empty dictionaries appear as <code>{}</code> and empty lists appear as <code>[]</code>.</li>
831833
<li>One space after the colon <code>:</code> for dictionary keys.</li>
832-
<li>Strings and numbers must be cannonically encoded. That is, they should be the form <em>produced</em> by <a href="https://www.ecma-international.org/ecma-262/6.0/#sec-json.stringify"><code>JSON.stringify</code></a></li>
834+
<li>Strings and numbers formatted according to the sections <em><a href="https://www.ecma-international.org/ecma-262/6.0/#sec-quotejsonstring">QuoteJSONString</a></em> and <em><a href="https://www.ecma-international.org/ecma-262/6.0/#sec-tostring-applied-to-the-number-type">ToString Applied to the Number Type</a></em>.
833835
<li>No trailing newline.</li>
834836
</ul>
835837
<aside>
836-
<p>Dictionary keys can appear in any order you choose, however the order needs to be remembered for later.
837-
</p>
838-
</aside>
839-
<aside>
840-
<p>valid JSON accepts forms that JSON.stringify does not produce. Scuttlebutt messages are a subset of valid JSON, that will restringify to the same bytes that was parsed. The reference implementation parses messages received over the network, then reserializes them before validating the signature and will not accept messages with fields that are not cannonically encoded.
841-
</p>
838+
<p>Dictionary keys can appear in any order you choose, however the order needs to be remembered for later.</p>
842839
</aside>
843840
<p>Then sign the message by computing:</p>
844841
<pre><code>signature = nacl_sign_detached(

0 commit comments

Comments
 (0)