Skip to content

Commit

Permalink
Readme formatting fix
Browse files Browse the repository at this point in the history
  • Loading branch information
dsharhon committed Mar 20, 2020
1 parent 1694299 commit 912048a
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 32 deletions.
63 changes: 33 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
mroot
================================================================================
Simple Merkle tree root calculator
=====
Simple Merkle root calculator

Node

Expand All @@ -16,50 +16,53 @@ Browser

Usage

`mroot(leaves, hasher, bitcoin = false)`
`mroot(leaves, hasher, compat = false)`

`leaves` your array or set of **pre-hashed** messages
`leaves` your ordered array or set of **pre-hashed** messages

`hasher` your pair-hashing function, e.g. `(a, b) => sha256(a + b)`

`bitcoin` whether to pad each layer to an even number of nodes by duplicating
the last leaf, if necessary, for compatibility with Satoshi's Merkle tree
`compat` whether to pad each layer to an even number of nodes by duplicating the
last leaf, if necessary, for compatibility with Satoshi's Merkle tree
implementation in Bitcoin

SECURITY NOTES
**Notes on Merkle tree security**

1. Each leaf must be externally validated, to protect against the second
preimage attack.

For example, given leaves `A = "alice"` and `B = "bob"`, the
root of `[A, B]` is the same as the root of just `[C]`, where `C =
hash("alice") + hash("bob")`.
1. Each leaf must be externally validated, to protect against the second
preimage attack.

YOU SHOULD BE OK if you reject `C` (e.g. because it's actually a binary hash
blob and you were expecting a name) and you don't permanently flag the root
itself as invalid (preventing you from accepting the legitimate `[A, B]`).
For example, given leaves `A = "alice"` and `B = "bob"`, the
root of `[A, B]` is the same as the root of just `[C]`, where `C =
hash("alice") + hash("bob")`.

https://crypto.stackexchange.com/questions/43430
YOU SHOULD BE OK if you reject `C` (e.g. because it's actually a binary hash
blob and you were expecting a name) and you don't permanently flag the root
itself as invalid (preventing you from accepting the legitimate `[A, B]`).

2. Do not use the root as an HMAC if your hasher is vulnerable to
length-extension.
https://crypto.stackexchange.com/questions/43430

For example, for your shared secret key `K` and message `M`, the naive signature
`sha256(K + M)` can be used by anyone to make `sha256(K + M + X)` to make it seem like you signed `X` as well.
2. Do not use the root as an HMAC if your hasher is vulnerable to
length-extension.

YOU SHOULD BE OK if you don't use shared-secret cryptography or you stick to
strictly-formatted messages.
For example, for your shared secret key `K` and message `M`, the naive
signature `sha256(K + M)` can be used by anyone to make `sha256(K + M + X)`
to make it seem like you signed `X` as well.

https://security.stackexchange.com/questions/20129
YOU SHOULD BE OK if you don't use shared-secret cryptography or you stick to
strictly-formatted messages.

3. Do not use the Bitcoin compatibility option unless you handle the fact that
you will get the same root with a potentially invalid, duplicated last-pair of
leaves.
https://security.stackexchange.com/questions/20129

For example, the leaves `[A, B, C]` will have the same root as the leaves
`[A, B, C, C]`. If you earmark the root itself as invalid because you don't like
`C` being duplicated, then you might accidentally reject `[A, B, C]` as well.
3. Do not use the Bitcoin compatibility option unless you handle the fact that
you will get the same root with a potentially invalid, duplicated last-pair
of leaves.

https://bitcointalk.org/?topic=102395
For example, the leaves `[A, B, C]` will have the same root as the leaves
`[A, B, C, C]`. If you earmark the root itself as invalid because you don't
like `C` being duplicated, then you might be tricked into rejecting
`[A, B, C]` as well.

https://bitcointalk.org/?topic=102395

By Dylan Sharhon, 2020
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "mroot",
"version": "2.0.1",
"description": "Minimalist Merkle root calculator",
"version": "2.0.2",
"description": "Simple Merkle root calculator",
"main": "mroot",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
Expand Down

0 comments on commit 912048a

Please sign in to comment.