aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorpukkamustard <pukkamustard@posteo.net>2020-10-22 11:54:36 +0200
committerpukkamustard <pukkamustard@posteo.net>2020-10-22 11:54:36 +0200
commit1e05ed9502dffbe0598edda5d271e517098c76a8 (patch)
treea4f4aab90b6f4626682dcd27c77452cf0f43f248 /doc
parentb32bd7e1ec11324e4d0d67a30d1793d97d39db84 (diff)
eris.adoc: notes on Block Size
Diffstat (limited to 'doc')
-rw-r--r--doc/eris.adoc51
1 files changed, 36 insertions, 15 deletions
diff --git a/doc/eris.adoc b/doc/eris.adoc
index ba1e867..4a681a6 100644
--- a/doc/eris.adoc
+++ b/doc/eris.adoc
@@ -2,7 +2,7 @@
pukkamustard <pukkamustard@posteo.net>
0.2.0-draft
:toc: left
-:stem:
+:xrefstyle: short
:sectnums:
:sectanchors:
@@ -55,10 +55,10 @@ ERIS is inspired and based on the encoding used in the file-sharing application
ERIS differs from ECRS in following points:
-Cryptographic primitives :: ECRS itself does not specify any cryptographic primitives but the GNUNet implementation uses the SHA-512 hash and AES cipher. ERIS uses the Blake2b-256 cryptographic hash <<RFC7693>> and the ChaCha20 stream cipher <<RFC8439>>. This improves performance, storage efficiency (as hash references are smaller) and allows a convergence secret to be used (via Blake2b keyed hashing; see section <<_convergence_secret>>).
-Block size :: ECRS uses a fixed block size of 32 Kb. This is inefficient when encoding small content. ERIS allows a block size of 1 Kb or 32 Kb, allowing efficient encoding of small and large content.
+Cryptographic primitives :: ECRS itself does not specify any cryptographic primitives but the GNUNet implementation uses the SHA-512 hash and AES cipher. ERIS uses the Blake2b-256 cryptographic hash <<RFC7693>> and the ChaCha20 stream cipher <<RFC8439>>. This improves performance, storage efficiency (as hash references are smaller) and allows a convergence secret to be used (via Blake2b keyed hashing; see <<_convergence_secret>>).
+Block size :: ECRS uses a fixed block size of 32 Kb. This is inefficient when encoding small content. ERIS allows a block size of 1 Kb or 32 Kb, allowing efficient encoding of small and large content (see <<_block_size>>).
URN :: ECRS does not specify an URN for referring to encoded content (this is specified as part of the GNUNet file-sharing application). ERIS specifies an URN for encoded content regardless of encoding application or storage and transport layer.
-Namespaces :: ECRS defines two mechanisms for grouping and discovering encoded content (SBlock and KBlock). ERIS does not specify any such mechanisms (see section <<_namespaces>>).
+Namespaces :: ECRS defines two mechanisms for grouping and discovering encoded content (SBlock and KBlock). ERIS does not specify any such mechanisms (see <<_namespaces>>).
Other related projects include Tahoe-LAFS and Freenet. The reader is referred to the ECRS paper <<ECRS>> for an in-depth explanation and comparison of related projects.
@@ -80,13 +80,28 @@ Padding algorithm :: According to ISO/IEC 7816-4.
=== Block Size
+ERIS uses two block sizes: 1Kb and 32Kb. The block size must be specified when encoding content.
+
+Both block sizes can be used to encode content of arbitrary size. The block size of 1Kb is an optimization towards smaller content.
+
+Content smaller than TODO SHOULD be encoded with block size 1Kb, content larger than TODO SHOULD be encoded with block size 32Kb.
+
+The block size is encoded in the read capability and the decoding process is capable of handling both cases.
+
+[NOTE]
+====
+When using block size 32Kb to encode content smaller than 1Kb, the content will be encoded in a 32Kb block. This is a storage overhead of over 3100%. When encoding very many pieces of small content (e.g. short messages or cartographic nodes) this overhead is not acceptable.
+
+On the other hand, using small block sizes increases the number of internal nodes that must be used to encode the content (see <<_merkle_tree>>). When encoding larger content it is more efficient to use a block size of 32Kb.
+====
+
=== Encoding
An overview of how content (sequence of bytes) is encoded using ERIS:
1. Split content into unencrypted blocks of size block size (see <<_splitting_input_content_into_blocks>>).
2. Encrypt unencrypted block and compute reference to encrypted block. This is a fundamental operation during encoding and described in section <<_reference_key_pair>>.
-3. Build a tree of nodes containing references to blocks by (see section <<_merkle_tree>>):
+3. Build a tree of nodes containing references to blocks by (see <<_merkle_tree>>):
- Collect references to encrypted blocks in a node of size block size
- Encrypt node and compute reference in the same way as for data blocks.
- Recursively collect references in nodes of higher level until there is only a single root node.
@@ -115,7 +130,7 @@ Encrypting a block and computing the reference-key pair is a fundamental operati
The encrypted block MUST be added to the output of the encoding process. The reference-key pair is returned and used for further processing.
-IMPORTANT: The convergence-secret MUST NOT be used to compute the reference to the encrypted block.
+The convergence-secret MUST NOT be used to compute the reference to the encrypted block.
===== Convergence Secret
@@ -133,13 +148,14 @@ The number of reference-key pairs collected into a node is called the _arity_ of
The output is the root reference-key pair and the level of the root reference-key pair.
-Figure <<figure_merkle_tree>> depicts a tree with four levels. The tree uses arity 2 for clarity (instead of 16 or 512).
+NOTE: The constructed tree of nodes containing reference-key pairs is called a Merkle Tree.
+
+A tree with for levels is depicted in <<figure_merkle_tree>>. For illustration purposes the tree is of arity 2 (instead of 16 or 512).
[[figure_merkle_tree]]
.Merkle Tree
-image::eris-merkle-tree.svg[Merkle Tree,opts=inline,width=80%]
+image::eris-merkle-tree.svg[Merkle Tree,opts=inline]
-The constructed tree of nodes containing reference-key pairs is called a Merkle Tree.
=== Decoding
@@ -147,12 +163,6 @@ The constructed tree of nodes containing reference-key pairs is called a Merkle
=== URN
-[quote, William Shakespeare, Comedy of Errors]
-____
-The one so like the other
-
-As could not be distinguish'd but by names.
-____
=== ERIS in Streaming Applications
@@ -170,6 +180,17 @@ ____
[appendix]
== Changelog
+[discrete]
+=== link:eris-v0.1.html[v0.1.0 (11. June 2020)]
+
+Initial version.
+
+[discrete]
+=== v0.2.0-draft (UNRELEASED)
+
+Major update of encoding that removes the _verification capability_ - ability to verify integrity of content without reading content.
+
+
[appendix]
== Copyright