com.guardtime.ksi.tree

Class BlindingMaskLinkingHashTreeBuilder

java.lang.Object

com.guardtime.ksi.tree.BlindingMaskLinkingHashTreeBuilder

All Implemented Interfaces:

TreeBuilder<ImprintNode>

public class BlindingMaskLinkingHashTreeBuilder
extends Object
implements TreeBuilder<ImprintNode>

Hash tree (aka Merkle tree) builder implementation using blinding masks.

Background: A strong hash function can’t be directly reversed to learn the input value from which the hash value in the chain was created. However, a typical log record may contain insufficient entropy to make that argument — an attacker who knows the pattern of the input could exhaustively test all possible variants to find the one that yields the hash value actually in the chain and thus learn the contents of the record. To prevent this kind of informed brute-force attack, a blinding mask with sufficient entropy can be added to each record before aggregating the hash values. (Source: https://www.researchgate.net/profile/Ahto_Truu/publication/290563005_Efficient_Record-Level_Keyless_Signatures_for_Audit_Logs/links/58b96d1092851c471d4a5888/Efficient-Record-Level-Keyless-Signatures-for-Audit-Logs.pdf page 3)

BlindingMaskLinkingHashTreeBuilder does not support IdentityMetadata aggregation and methods add(ImprintNode, IdentityMetadata) and calculateHeight(ImprintNode, IdentityMetadata) will throw an UnsupportedOperationException exception.

This builder can not be used multiple times and it is not thread safe.

Field Summary

Fields

Modifier and Type	Field and Description
protected static long	MASKED_NODE_LEVEL

Constructor Summary

Constructors

Constructor and Description
BlindingMaskLinkingHashTreeBuilder(byte[] initializationVector) Creates an instance of BlindingMaskLinkingHashTreeBuilder using a Util.DEFAULT_AGGREGATION_ALGORITHM hash algorithm and a zero hash value as previous block hash.
BlindingMaskLinkingHashTreeBuilder(byte[] initializationVector, DataHash previousBlockHash) Creates an instance of BlindingMaskLinkingHashTreeBuilder using Util.DEFAULT_AGGREGATION_ALGORITHM hash algorithm and a DataHash from previous block.
BlindingMaskLinkingHashTreeBuilder(HashAlgorithm algorithm, byte[] initializationVector, DataHash previousBlockHash) Creates an instance of BlindingMaskLinkingHashTreeBuilder.
BlindingMaskLinkingHashTreeBuilder(HashAlgorithm algorithm, byte[] initializationVector, DataHash previousBlockHash, TreeBuilder<ImprintNode> treeBuilder) Creates an instance of BlindingMaskLinkingHashTreeBuilder.

Method Summary

Modifier and Type	Method and Description
void	add(ImprintNode... nodes) Adds a new list of leaves to the binary tree.
void	add(ImprintNode node) Adds a new node to the tree.
void	add(ImprintNode node, IdentityMetadata metadata) IdentityMetadata isn't supported by BlindingMaskLinkingHashTreeBuilder and this method always throws an UnsupportedOperationException exception.
ImprintNode	build() Builds the binary tree and returns the root hash of the tree.
protected ImprintNode	calculateBlindingMaskNode()
long	calculateHeight(ImprintNode node) Calculates the binary tree height if new leaf would be added.
long	calculateHeight(ImprintNode node, IdentityMetadata metadata) IdentityMetadata isn't supported by BlindingMaskLinkingHashTreeBuilder.
protected ImprintNode	calculateNewNode(ImprintNode node)
DataHash	getLastNodeHash() Returns the last leaf hash of this block/tree (for linking next block/tree).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MASKED_NODE_LEVEL

protected static final long MASKED_NODE_LEVEL

See Also:

Constant Field Values

Constructor Detail

BlindingMaskLinkingHashTreeBuilder

public BlindingMaskLinkingHashTreeBuilder(byte[] initializationVector)

Creates an instance of BlindingMaskLinkingHashTreeBuilder using a Util.DEFAULT_AGGREGATION_ALGORITHM hash algorithm and a zero hash value as previous block hash.

Parameters:

initializationVector - initialization vector used to calculate masking nodes, must not be null. The length of the initialization vector should be as long as the output of the Util.DEFAULT_AGGREGATION_ALGORITHM hash algorithm.

Throws:

IllegalArgumentException - if initializationVector length is not as long as the output of the Util.DEFAULT_AGGREGATION_ALGORITHM hash algorithm.

NullPointerException - if one of the required input parameters is null.

BlindingMaskLinkingHashTreeBuilder

public BlindingMaskLinkingHashTreeBuilder(byte[] initializationVector,
                                          DataHash previousBlockHash)

Creates an instance of BlindingMaskLinkingHashTreeBuilder using Util.DEFAULT_AGGREGATION_ALGORITHM hash algorithm and a DataHash from previous block.

Parameters:

previousBlockHash - previous block data hash used to calculate first blinding mask, must not be null.

initializationVector - initialization vector used to calculate masking nodes, must not be null. The length of the initialization vector should be as long as the output of the Util.DEFAULT_AGGREGATION_ALGORITHM hash algorithm.

Throws:

IllegalArgumentException - if initializationVector length is not as long as the output of the Util.DEFAULT_AGGREGATION_ALGORITHM hash algorithm.

NullPointerException - if one of the required input parameters is null.

BlindingMaskLinkingHashTreeBuilder

public BlindingMaskLinkingHashTreeBuilder(HashAlgorithm algorithm,
                                          byte[] initializationVector,
                                          DataHash previousBlockHash)

Creates an instance of BlindingMaskLinkingHashTreeBuilder.

Parameters:

algorithm - hash algorithm used to calculate inner nodes of the hash tree, must not be null.

initializationVector - initialization vector used to calculate masking nodes, must not be null. The length of the initialization vector should be as long as the output of the hash algorithm.

previousBlockHash - previous block data hash used to calculate first blinding mask, must not be null.

Throws:

IllegalArgumentException - if initializationVector length is not as long as the output of the algorithm hash algorithm.

NullPointerException - if one of the required input parameters is null.

BlindingMaskLinkingHashTreeBuilder

public BlindingMaskLinkingHashTreeBuilder(HashAlgorithm algorithm,
                                          byte[] initializationVector,
                                          DataHash previousBlockHash,
                                          TreeBuilder<ImprintNode> treeBuilder)

Creates an instance of BlindingMaskLinkingHashTreeBuilder.

Parameters:

algorithm - hash algorithm used to calculate inner nodes of the hash tree, must not be null.

initializationVector - initialization vector used to calculate masking nodes, must not be null. The length of the initialization vector should be as long as the output of the hash algorithm.

previousBlockHash - previous block data hash used to calculate first blinding mask, must not be null.

treeBuilder - implementation of TreeBuilder to use when building the tree.

Throws:

IllegalArgumentException - if initializationVector length is not as long as the output of the algorithm hash algorithm.

NullPointerException - if one of the required input parameters is null.

Method Detail

add

public void add(ImprintNode node)
         throws KSIException

Adds a new node to the tree.

Specified by:

add in interface TreeBuilder<ImprintNode>

Parameters:

node - a leaf to add to the tree, must not be null. The level of the node must be 0.

Throws:

IllegalArgumentException - if node level is greater than 0.

KSIException

add

public void add(ImprintNode node,
                IdentityMetadata metadata)

IdentityMetadata isn't supported by BlindingMaskLinkingHashTreeBuilder and this method always throws an UnsupportedOperationException exception.

Specified by:

add in interface TreeBuilder<ImprintNode>

Parameters:

node - leaf node to be added, must not be null.

metadata - node's metadata, must not be null

calculateHeight

public long calculateHeight(ImprintNode node)
                     throws KSIException

Calculates the binary tree height if new leaf would be added.

Specified by:

calculateHeight in interface TreeBuilder<ImprintNode>

Parameters:

node - a leaf to be added to the tree, must not be null. The level of the node must be 0.

Returns:

Hash tree height.

Throws:

IllegalArgumentException - if node level is greater than 0.

KSIException

calculateHeight

public long calculateHeight(ImprintNode node,
                            IdentityMetadata metadata)

IdentityMetadata isn't supported by BlindingMaskLinkingHashTreeBuilder. This method always throws an UnsupportedOperationException exception.

Specified by:

calculateHeight in interface TreeBuilder<ImprintNode>

Parameters:

node - a leaf to be added to the tree, must not be null.

metadata - node's metadata, must not be null

Returns:

Binary tree height.

add

public void add(ImprintNode... nodes)
         throws KSIException

Adds a new list of leaves to the binary tree.

Specified by:

add in interface TreeBuilder<ImprintNode>

Parameters:

nodes - a list of leaves to be added to the tree, must not be null.

Throws:

IllegalArgumentException - if node level is greater than 0.

KSIException

build

public ImprintNode build()
                  throws KSIException

Builds the binary tree and returns the root hash of the tree.

Specified by:

build in interface TreeBuilder<ImprintNode>

Returns:

Root hash of the tree.

Throws:

KSIException

calculateNewNode

protected ImprintNode calculateNewNode(ImprintNode node)

calculateBlindingMaskNode

protected ImprintNode calculateBlindingMaskNode()

getLastNodeHash

public DataHash getLastNodeHash()

Returns the last leaf hash of this block/tree (for linking next block/tree).