LIBMERKLETREE(3)

NAME
libmerkletree - Merkle tree construction and verification

LIBRARY
libmerkletree

SYNOPSIS
#include <merkletree.h>

int
merkletree_file(merkletree_t *tree, const char *f, const char *algorithm, size_t blocksize);
int
merkletree_data(merkletree_t *tree, const void *p, size_t size, const char *algorithm, size_t blocksize);
void
merkletree_free(merkletree_t *tree);
int
merkletree_snprintf(merkletree_t *tree, const void *f, const char *buf, size_t size);
int
merkletree_asprintf(merkletree_t *tree, const void *f, const char **buf);
int
merkletree_sum_info(merkletree_t *tree, const void *f, const char **buf);
int
merkletree_verify(const void *sumfile, const char *filename);

DESCRIPTION
The libmerkletree library implements Merkle tree calculation, and also includes some higher-level functions to verify a file against a previously-generated Merkle tree.

A Merkle tree is a hash tree calculated across blocks in data. Any block size can be specified in this implementation. A digest is calculated across each block in the data, and then a digest is calculated across blocks of the checksums, and this continues until only one block of digest exists. The hierarchical nature of this allows individual blocks of a file to be verified, even if other parts of the file have been modified. A degenerate case, in which the data is less than the blocksize, will mean that a single digest value for the block is calculated. This will be the same as the digest algorithm applied to the whole file.

The digest calculations themselves are done by the libmultigest(3) library, and allow concatenation of multiple digests to produce a single large digest value.

A tree of digests is calculated using either merkletree_file() or merkletree_data() and can then be retrieved in an understandable form using either merkletree_snprintf() or merkletree_asprintf() which is in string format. The functions differ in the way the arguments are passed in. In both cases, the number of bytes in the output text is returned.

The information from the calculated digests, including digest algorithm and blocksize, can be retrieved using merkletree_sum_info() and a file may be verified against a previously calculated tree using the merkletree_verify() function. The merkletree_verify() function returns 1 if the files matched, and 0 otherwise.

Finally, resources allocated can be freed using the merkletree() function.

SEE ALSO
libmultigest(3)

HISTORY
The libmerkletree library first appeared in NetBSD 7.0.

AUTHORS
Alistair Crooks <agc@NetBSD.org>