mirror of
https://github.com/Stichting-MINIX-Research-Foundation/pkgsrc-ng.git
synced 2025-09-14 14:56:21 -04:00
128 lines
4.1 KiB
Groff
128 lines
4.1 KiB
Groff
.\" $NetBSD: libmerkletree.3,v 1.1.1.1 2014/03/05 05:19:25 agc Exp $
|
|
.\"
|
|
.\" Copyright (c) 2014 Alistair Crooks <agc@NetBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"/
|
|
.Dd March 3, 2014
|
|
.Dt LIBMERKLETREE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libmerkletree
|
|
.Nd Merkle tree construction and verification
|
|
.Sh LIBRARY
|
|
.Lb libmerkletree
|
|
.Sh SYNOPSIS
|
|
.In merkletree.h
|
|
.Pp
|
|
.Ft int
|
|
.Fo merkletree_file
|
|
.Fa "merkletree_t *tree" "const char *f" "const char *algorithm" "size_t blocksize"
|
|
.Fc
|
|
.Ft int
|
|
.Fo merkletree_data
|
|
.Fa "merkletree_t *tree" "const void *p" "size_t size" "const char *algorithm" "size_t blocksize"
|
|
.Fc
|
|
.Ft void
|
|
.Fo merkletree_free
|
|
.Fa "merkletree_t *tree"
|
|
.Fc
|
|
.Ft int
|
|
.Fo merkletree_snprintf
|
|
.Fa "merkletree_t *tree" "const void *f" "const char *buf" "size_t size"
|
|
.Fc
|
|
.Ft int
|
|
.Fo merkletree_asprintf
|
|
.Fa "merkletree_t *tree" "const void *f" "const char **buf"
|
|
.Fc
|
|
.Ft int
|
|
.Fo merkletree_sum_info
|
|
.Fa "merkletree_t *tree" "const void *f" "const char **buf"
|
|
.Fc
|
|
.Ft int
|
|
.Fo merkletree_verify
|
|
.Fa "const void *sumfile" "const char *filename"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library implements Merkle tree calculation, and also includes
|
|
some higher-level functions to verify a file against a previously-generated
|
|
Merkle tree.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The digest calculations themselves are done by the
|
|
.Xr libmultigest 3
|
|
library, and allow concatenation of multiple digests to produce a
|
|
single large digest value.
|
|
.Pp
|
|
A tree of digests is calculated using either
|
|
.Fn merkletree_file
|
|
or
|
|
.Fn merkletree_data
|
|
and can then be retrieved in an understandable form using either
|
|
.Fn merkletree_snprintf
|
|
or
|
|
.Fn 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.
|
|
.Pp
|
|
The information from the calculated digests, including digest
|
|
algorithm and blocksize, can be retrieved using
|
|
.Fn merkletree_sum_info
|
|
and a file may be verified against a previously calculated tree
|
|
using the
|
|
.Fn merkletree_verify
|
|
function.
|
|
The
|
|
.Fn merkletree_verify
|
|
function returns
|
|
.Dv 1
|
|
if the files matched,
|
|
and
|
|
.Dv 0
|
|
otherwise.
|
|
.Pp
|
|
Finally, resources allocated can be freed using the
|
|
.Fn merkletree
|
|
function.
|
|
.Sh SEE ALSO
|
|
.Xr libmultigest 3
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
library first appeared in
|
|
.Nx 7.0 .
|
|
.Sh AUTHORS
|
|
.An Alistair Crooks Aq agc@NetBSD.org
|