diff --git a/README.md b/README.md index 605a252..8633618 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ mroot -================================================================================ -Simple Merkle tree root calculator +===== +Simple Merkle root calculator Node @@ -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 diff --git a/package.json b/package.json index feb5009..1c6629e 100644 --- a/package.json +++ b/package.json @@ -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"