aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorpukkamustard <pukkamustard@posteo.net>2020-10-28 16:42:47 +0100
committerpukkamustard <pukkamustard@posteo.net>2020-10-28 16:42:47 +0100
commit7c3e4ae09048f8ac5137ca894c8324f93236adcc (patch)
tree24a838012477f4ce199f4a208402968e83addbd5
parent452eaf550b8d7ee6dd26a44352eec9b763b3a66b (diff)
eris.adoc: describe test vectors
-rw-r--r--doc/eris.adoc46
-rw-r--r--public/index.html93
2 files changed, 136 insertions, 3 deletions
diff --git a/doc/eris.adoc b/doc/eris.adoc
index 40234b2..19b2afc 100644
--- a/doc/eris.adoc
+++ b/doc/eris.adoc
@@ -359,6 +359,52 @@ A reference implementation is available in Guile: https://gitlab.com/openengiadi
[appendix]
== Test Vectors
+=== Machine Readable
+
+A set of test vectors are provided in the https://gitlab.com/openengiadina/eris/-/tree/main/test-vectors[ERIS repository]. Implementations of the ERIS encoding MUST be able to satisfy the test vectors.
+
+The test vectors are given as machine-readable JSON files. For example the test vector `eris-test-vector-00.json`:
+
+[source,json]
+----
+{
+ "id": 0,
+ "name": "short string (block size 1Kb)",
+ "description": "Encode the UTF-8 encoding of the string \"Hail ERIS!\" with block-size 1Kb and null convergence-secret.",
+ "content": "JBQWS3BAIVJESUZB",
+ "convergence-secret": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+ "block-size": 1024,
+ "read-capability": {
+ "block-size": 1024,
+ "level": 0,
+ "root-reference": "BLY4QKPNR57OKIOA5BLPI5NHQHKN3GJR5F4RNY6TZFAXKSSLYYQQ",
+ "root-key": "JUNNKQN544MJJMGRABGDOTJAQCGF4U4Q6YW3VVHD4FGQYUSJ4YOA"
+ },
+ "urn": "urn:erisx2:AAAAV4OIFHWY67XFEHAOQVXUOWTYDVG5TEY6S6IW4PJ4SQLVJJF4MIKNDLKUDPPHDCKLBUIAJQ3U2IEARRPFHEHWFW5NJY7BJUGFESPGDQ",
+ "blocks": {
+ "BLY4QKPNR57OKIOA5BLPI5NHQHKN3GJR5F4RNY6TZFAXKSSLYYQQ": "Y5JKORBMSAMYSSNW5CJN3GPNMY6G6MJ3EWNEBE5W2KT6PTN3XETYGQ6N47ZK7NSE2VQZPH7RQOF53UATSC7HO7AK6K3K3VI7A2CQOIQIFVO7F2JTBA7EQ3U7TXND5EUNX2GIVARNJ4DC5UBADDDJKZ3ILMVMW3NT5H6LTWD4QTRLYHXZBRK3GUM5XSYEDJ2MTYHHB4DWFKVR5IN62ZUWTEVFMAEHIF655PL4DUQ4T6XAHBMAXTJOOMIS2BIRD3SLPRQZABTWUTFZXMQF2JBUYUZ45SXJIFX2AOFGIHSMH5DY274W4BJXCZULZUMAQQ3JKHQIUJX5NGDZF4HPTHEHI4S6ZJWRJ53SQ767OT63OESXBVR66ZEBPGSEIP2LBXAWWL2F6YHB4R2OOMQWWFVK62GMRZ22DPHHS5ZOQTYU5VHK44Y4OIFVI4SVST6NOQGMWRRS7HAIBF6QP463A5J36RP2XLC2EVSN6FOX4R5G4JMT6TAFIJQMRD4GUNATZ7YDDNNJUGJK27ILNFQLJYD6A7JV7R5ZAL6G6MPT6S3LNNID6ACS6BYE43OQHQ6OUFOQPTGAOWT3BFXEUHPYDSI3CP72S7FVH2BKWLMIBKNSTM272CY7XFONZFUZS6IRPKT3MTI3LOVSJRJK3YUR2TVLSK3EFWJAZRMP2PFLRBEQT6Q2RTCIJI2QB5PBZTSJDTU37J3VHMI6F275AFPMJOOQTLCBTAWD5W2GITDM545CVFCGZ6LYK65GRQPZEISY2HA764K3ST6UUDXFW5LL2VKK2RHA3MNPIIMZPM22BGSZRQEQPGQXEQU3B5LYC42EQMOHCGLRIL6VUAODWYYGASLF2F6LQAE22AXJHPU76HSFGT7DICZ7O6WMUWEMYDOCAP5AB5OFWYRJ7JKR574RB6UE55XPNKXPQP32VYBSGMMGSSGFFQU25AQSNIZYSMRLDIPUY4L35ZMFX4LVS2JTXC4K6NPOH7F3QWE6WT463OETVGIJSYRVU4O4F6YPSBJDN5QC3AFAU5HKJRNOSDAVLNJ7V3FWBUHDL5VY3PEXECOKI6BKGUE27NDKC4DJRRBOTU22CIDTYX4YCGIPGFO4UG2AK5EI54DSU75BCQ5SSFWSKB3JY2SLAA6EJQR7TDSGEOZK7F74Q7UHWVV4YS6GWMOCSCFQF7TMLDA5BB7MZYTX7QSUYNCRUKHOBONPHYSFBIUZON5XBWRBXIIHJGDJYX5BBBCQZWWHJZXGPC7G45VXKT7Y6RUR254FF2OPJGQEHWNKJ47QR3EXQQIA3MYK542XBOAWLOIHSJCP447WF74DDVFK7LM2DRFHW2RVX3EX3C5VXQT6XHJLPED3XJ5EW75323XN2YLVKKNUP45P7GYOORBYMSNB4MM24H3UY7JAMYTIYOBGTMVV2W6PMVFWNPPSE3AXFPS6GNBTQTAUUPJDXFREUMZOZGLD5VGO7PWRSL2GQP7MDY2IPHQCMTCOFYKSPGMI6OFUELITQPFTZUM7V2IZOMPIXKHLTBSRZUFLABZXSPHWZ626OFJ6WI7KUW4AT3KMMEO33FH3QGTOKCAACPQYM7UCFHN5QGQCVB7SEH6WXISV6AJB7LCDLKRM6JCANOBLDD57Z44GHLIYEJI"
+ }
+}
+----
+
+The fields of JSON test vectors are:
+
+`id` :: Numeric identifier of the test vector.
+`name` :: Short human readable name.
+`description` :: Human readable description of the test.
+`content` :: The binary content to be encoded as Base32 (unpadded) string.
+`convergence-secret` :: The convergence secret to be used as Base32 string.
+`block-size` :: Block size that should be used for encoding in bytes (either 1024 or 32768).
+`read-capability` :: JSON map containing the components of the read capability. This is not used in tests but is here as a help for developers.
+`urn` :: The ERIS URN of the content.
+`blocks` :: A JSON map of blocks required to decode the content given the URN. Key and field are encoded as Base32 strings.
+
+Implementations MUST verify that the content encodes to the URN given the specified block size and convergence secret and verify that given the URN and blocks the content can be decoded.
+
+=== Large content
+
+TODO some test cases that are too big to fit into a JSON file. E.g. 1 TB of data that can be generated so is encoded to the URN so.
+
[appendix]
== Changelog
diff --git a/public/index.html b/public/index.html
index c977bec..f557108 100644
--- a/public/index.html
+++ b/public/index.html
@@ -474,7 +474,12 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
</li>
<li><a href="#_implementations">4. Implementations</a></li>
<li><a href="#_acknowledgments">5. Acknowledgments</a></li>
-<li><a href="#_test_vectors">Appendix A: Test Vectors</a></li>
+<li><a href="#_test_vectors">Appendix A: Test Vectors</a>
+<ul class="sectlevel2">
+<li><a href="#_machine_readable">A.1. Machine Readable</a></li>
+<li><a href="#_large_content">A.2. Large content</a></li>
+</ul>
+</li>
<li><a href="#_changelog">Appendix B: Changelog</a></li>
<li><a href="#_copyright">Appendix C: Copyright</a></li>
<li><a href="#_references">References</a></li>
@@ -1471,7 +1476,89 @@ ERIS-Decode(BLOCK-SIZE, LEVEL, ROOT-REFERENCE, ROOT-KEY):
<div class="sect1">
<h2 id="_test_vectors"><a class="anchor" href="#_test_vectors"></a>Appendix A: Test Vectors</h2>
<div class="sectionbody">
-
+<div class="sect2">
+<h3 id="_machine_readable"><a class="anchor" href="#_machine_readable"></a>A.1. Machine Readable</h3>
+<div class="paragraph">
+<p>A set of test vectors are provided in the <a href="https://gitlab.com/openengiadina/eris/-/tree/main/test-vectors">ERIS repository</a>. Implementations of the ERIS encoding MUST be able to satisfy the test vectors.</p>
+</div>
+<div class="paragraph">
+<p>The test vectors are given as machine-readable JSON files. For example the test vector <code>eris-test-vector-00.json</code>:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-json" data-lang="json">{
+ "id": 0,
+ "name": "short string (block size 1Kb)",
+ "description": "Encode the UTF-8 encoding of the string \"Hail ERIS!\" with block-size 1Kb and null convergence-secret.",
+ "content": "JBQWS3BAIVJESUZB",
+ "convergence-secret": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+ "block-size": 1024,
+ "read-capability": {
+ "block-size": 1024,
+ "level": 0,
+ "root-reference": "BLY4QKPNR57OKIOA5BLPI5NHQHKN3GJR5F4RNY6TZFAXKSSLYYQQ",
+ "root-key": "JUNNKQN544MJJMGRABGDOTJAQCGF4U4Q6YW3VVHD4FGQYUSJ4YOA"
+ },
+ "urn": "urn:erisx2:AAAAV4OIFHWY67XFEHAOQVXUOWTYDVG5TEY6S6IW4PJ4SQLVJJF4MIKNDLKUDPPHDCKLBUIAJQ3U2IEARRPFHEHWFW5NJY7BJUGFESPGDQ",
+ "blocks": {
+ "BLY4QKPNR57OKIOA5BLPI5NHQHKN3GJR5F4RNY6TZFAXKSSLYYQQ": "Y5JKORBMSAMYSSNW5CJN3GPNMY6G6MJ3EWNEBE5W2KT6PTN3XETYGQ6N47ZK7NSE2VQZPH7RQOF53UATSC7HO7AK6K3K3VI7A2CQOIQIFVO7F2JTBA7EQ3U7TXND5EUNX2GIVARNJ4DC5UBADDDJKZ3ILMVMW3NT5H6LTWD4QTRLYHXZBRK3GUM5XSYEDJ2MTYHHB4DWFKVR5IN62ZUWTEVFMAEHIF655PL4DUQ4T6XAHBMAXTJOOMIS2BIRD3SLPRQZABTWUTFZXMQF2JBUYUZ45SXJIFX2AOFGIHSMH5DY274W4BJXCZULZUMAQQ3JKHQIUJX5NGDZF4HPTHEHI4S6ZJWRJ53SQ767OT63OESXBVR66ZEBPGSEIP2LBXAWWL2F6YHB4R2OOMQWWFVK62GMRZ22DPHHS5ZOQTYU5VHK44Y4OIFVI4SVST6NOQGMWRRS7HAIBF6QP463A5J36RP2XLC2EVSN6FOX4R5G4JMT6TAFIJQMRD4GUNATZ7YDDNNJUGJK27ILNFQLJYD6A7JV7R5ZAL6G6MPT6S3LNNID6ACS6BYE43OQHQ6OUFOQPTGAOWT3BFXEUHPYDSI3CP72S7FVH2BKWLMIBKNSTM272CY7XFONZFUZS6IRPKT3MTI3LOVSJRJK3YUR2TVLSK3EFWJAZRMP2PFLRBEQT6Q2RTCIJI2QB5PBZTSJDTU37J3VHMI6F275AFPMJOOQTLCBTAWD5W2GITDM545CVFCGZ6LYK65GRQPZEISY2HA764K3ST6UUDXFW5LL2VKK2RHA3MNPIIMZPM22BGSZRQEQPGQXEQU3B5LYC42EQMOHCGLRIL6VUAODWYYGASLF2F6LQAE22AXJHPU76HSFGT7DICZ7O6WMUWEMYDOCAP5AB5OFWYRJ7JKR574RB6UE55XPNKXPQP32VYBSGMMGSSGFFQU25AQSNIZYSMRLDIPUY4L35ZMFX4LVS2JTXC4K6NPOH7F3QWE6WT463OETVGIJSYRVU4O4F6YPSBJDN5QC3AFAU5HKJRNOSDAVLNJ7V3FWBUHDL5VY3PEXECOKI6BKGUE27NDKC4DJRRBOTU22CIDTYX4YCGIPGFO4UG2AK5EI54DSU75BCQ5SSFWSKB3JY2SLAA6EJQR7TDSGEOZK7F74Q7UHWVV4YS6GWMOCSCFQF7TMLDA5BB7MZYTX7QSUYNCRUKHOBONPHYSFBIUZON5XBWRBXIIHJGDJYX5BBBCQZWWHJZXGPC7G45VXKT7Y6RUR254FF2OPJGQEHWNKJ47QR3EXQQIA3MYK542XBOAWLOIHSJCP447WF74DDVFK7LM2DRFHW2RVX3EX3C5VXQT6XHJLPED3XJ5EW75323XN2YLVKKNUP45P7GYOORBYMSNB4MM24H3UY7JAMYTIYOBGTMVV2W6PMVFWNPPSE3AXFPS6GNBTQTAUUPJDXFREUMZOZGLD5VGO7PWRSL2GQP7MDY2IPHQCMTCOFYKSPGMI6OFUELITQPFTZUM7V2IZOMPIXKHLTBSRZUFLABZXSPHWZ626OFJ6WI7KUW4AT3KMMEO33FH3QGTOKCAACPQYM7UCFHN5QGQCVB7SEH6WXISV6AJB7LCDLKRM6JCANOBLDD57Z44GHLIYEJI"
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The fields of JSON test vectors are:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>id</code> </dt>
+<dd>
+<p>Numeric identifier of the test vector.</p>
+</dd>
+<dt class="hdlist1"><code>name</code> </dt>
+<dd>
+<p>Short human readable name.</p>
+</dd>
+<dt class="hdlist1"><code>description</code> </dt>
+<dd>
+<p>Human readable description of the test.</p>
+</dd>
+<dt class="hdlist1"><code>content</code> </dt>
+<dd>
+<p>The binary content to be encoded as Base32 (unpadded) string.</p>
+</dd>
+<dt class="hdlist1"><code>convergence-secret</code> </dt>
+<dd>
+<p>The convergence secret to be used as Base32 string.</p>
+</dd>
+<dt class="hdlist1"><code>block-size</code> </dt>
+<dd>
+<p>Block size that should be used for encoding in bytes (either 1024 or 32768).</p>
+</dd>
+<dt class="hdlist1"><code>read-capability</code> </dt>
+<dd>
+<p>JSON map containing the components of the read capability. This is not used in tests but is here as a help for developers.</p>
+</dd>
+<dt class="hdlist1"><code>urn</code> </dt>
+<dd>
+<p>The ERIS URN of the content.</p>
+</dd>
+<dt class="hdlist1"><code>blocks</code> </dt>
+<dd>
+<p>A JSON map of blocks required to decode the content given the URN. Key and field are encoded as Base32 strings.</p>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p>Implementations MUST verify that the content encodes to the URN given the specified block size and convergence secret and verify that given the URN and blocks the content can be decoded.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_large_content"><a class="anchor" href="#_large_content"></a>A.2. Large content</h3>
+<div class="paragraph">
+<p>TODO some test cases that are too big to fit into a JSON file. E.g. 1 TB of data that can be generated so is encoded to the URN so.</p>
+</div>
+</div>
</div>
</div>
<div class="sect1">
@@ -1543,7 +1630,7 @@ ERIS-Decode(BLOCK-SIZE, LEVEL, ROOT-REFERENCE, ROOT-KEY):
</div>
<div id="footer">
<div id="footer-text">
-Last updated 2020-10-27 08:13:03 +0100
+Last updated 2020-10-28 16:42:02 +0100
</div>
</div>
</body>