A Python library for constructing Merkle Trees and validating Log Proofs
Project description
pymerkle: A Python library for constructing Merkle Trees and validating Log Proofs
Complete documentation can be found at pymerkle.readthedocs.org.
This library implements
- a class for binary balanced Merkle-Trees (with possibly odd number of leaves) capable of generating consistency-proofs except for audit-proofs (along with inclusion-tests), supporting all hashing algorithms (including SHA3 variations) and most encoding types provided by
Python>=3.6
- defense against second-preimage attack
- flexible mechanisms for validating the generated proofs
It is currently the only Python library implementing all the above features, with an eye on protocols like Certificate Transparency and real-life applications.
Installation
pip3 install pymerkle
Quick example
See also Usage and API
from pymerkle import * # Import merkle_tree, validate_proof
# and proof_validator
tree = merkle_tree() # Create empty SHA256/UTF-8 Merkle-tree with
# defense against second-preimage attack
validator = proof_validator() # Create object for validating proofs
# Successively update the tree with one hundred records
for i in range(100):
tree.update(bytes('{}-th record'.format(i), 'utf-8'))
p = tree.audit_proof(b'12-th record') # Generate audit-proof for the given record
q = tree.audit_proof(55) # Generate audit-proof based upon the 56-th leaf
# Quick validation of the above proofs
validate_proof(target_hash=tree.root_hash(), proof=p) # True
validate_proof(target_hash=tree.root_hash(), proof=q) # True
# Store the tree's current state (root-hash and length) for later use
top_hash = tree.root_hash()
length = tree.length()
# Update the tree by encrypting a new log
tree.encrypt_log('logs/sample_log')
# Generate consistency-proof for the stage before encrypting the log
r = tree.consistency_proof(old_hash=top_hash, sublength=length)
# Validate consistency-proof and generate receipt
validation_receipt = validator.validate(target_hash=tree.root_hash(), proof=r)
Tree structure
Contrary to most implementations, the Merkle-tree is here always binary balanced, with all nodes except for the exterior ones (leaves) having two parents. This is achieved as follows: upon appending a block of new leaves, instead of promoting a lonely leaf or duplicating it, a bifurcation node gets created so that trees with the same number of leaves have always identical structure and input clashes among growing strategies be avoided (independently of the configured hash and encoding types). This standardization is further crucial for:
- fast generation of consistency-proof paths (based on additive decompositions in decreasing powers of 2)
- fast recalculation of the root-hash after appending a new leaf, since only the hashes at the tree's left-most branch need be recalculated
- memory efficiency, since the height as well as total number of nodes with respect to the tree's length is controlled to the minimum. For example, a tree with 9 leaves has 17 nodes in the present implementation, whereas the total number of nodes in the structure described here is 20.
The topology is namely identical to that of a binary Sekura tree, depicted in Section 5.4 of this paper. Follow the straightforward algorithm of the pymerkle.merkle_tree.update
method for further insight, or the gradual development exposed in the tests/test_tree_structure.py
file inside the project's repository.
Deviation from bitcoin specification
In contrast to the bitcoin specification for Merkle-trees, lonely leaves are not duplicated in order for the tree to remain genuinely binary. Instead, creating bifurcation nodes at the rightmost branch allows the tree remains balanced upon any update. As a consequence, even if security against second-preimage attack (see below) were deactivated, the current implementation by structure invulnerable to the kind of attack that is described here.
Defense against second-preimage attack
Defense against second-preimage attack is by default activated. Roughly speaking, it consists in the following security measures:
-
Before calculating the hash of a leaf, prepend the corresponding record with the null hexadecimal
0x00
-
Before calculating the hash any interior node, prepend both of its parents' hashes with the unit hexadecimal
0x01
(See here or here for some insight). Read the tests/test_defense.py
file inside the project's repository to see how to perform second-preimage attacks against the current implementation.
Running tests
In order to run all integration tests, execute
./run_tests.sh
from inside the root directory of the project. Alternatively, run the command pytest tests/
. You can run only a specific test file, e.g., test_log_encryption.py
, with the command pytest tests/test_log_encryption.py
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.