pkgsrc/security/multigest/files/libmultigest.3

.\" $NetBSD: libmultigest.3,v 1.2 2015/02/12 01:57:57 agc Exp $
.\"
.\" Copyright (c) 2013,2014,2015 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 February 11, 2015
.Dt LIBMULTIGEST 3
.Os
.Sh NAME
.Nm libmultigest
.Nd Multiple digest library
.Sh LIBRARY
.Lb libmultigest
.Sh SYNOPSIS
.In multigest.h
.Ft multigest_t *
.Fo multigest_new
.Fa "void"
.Fc
.Ft int
.Fo multigest_init
.Fa "multigest_t *mg" "const char *algorithms"
.Fc
.Ft int
.Fo multigest_add_subst
.Fa "multigest_t *mg" "const char *substregex" "const char *replacement"
.Fc
.Ft void
.Fo multigest_update
.Fa "multigest_t *mg" "const void *data" "size_t length"
.Fc
.Ft void
.Fo multigest_final
.Fa "unsigned char *rawdigest" "multigest_t *mg"
.Fc
.Ft "uint8_t *"
.Fo multigest_data
.Fa "const char *algorithms" "const void *data" "size_t length"
.Fa "const unsigned char *rawoutput" "const char *substregex"
.Fa "const char *replacement"
.Fc
.Ft "uint8_t *"
.Fo multigest_file
.Fa "const char *algorithms" "const char *filename"
.Fa "const unsigned char *rawoutput" "const char *substregex"
.Fa "const char *replacement"
.Fc
.Ft uint32_t
.Fo multigest_get_rawsize
.Fa "multigest_t *mg"
.Fc
.Ft uint32_t
.Fo multigest_algs_rawsize
.Fa "const char *algnames"
.Fc
.Ft int
.Fo multigest_format_hex
.Fa "unsigned char *rawinput" "const char *algorithms"
.Fa "char *output" "size_t outputsize"
.Fc
.Ft int
.Fo multigest_print_hex
.Fa "unsigned char *rawinput" "const char *algorithms"
.Fa "const char *outname" "const char *filename" "const char *substregex"
.Fa "const char *output_separator" "const char *output_format"
.Fc
.Ft char *
.Fo multigest_format_raw
.Fa "const uint8_t *rawinput" "size_t insize"
.Fa "char *fmtoutput" "size_t outsize"
.Fc
.Sh DESCRIPTION
.Nm
is a library interface to calculate multiple digests
at the same time, without having to re-scan data.
This is to protect against any single digest algorithm
being found to have second pre-images.
Up to 32 digests can be specified on the command line.
.Pp
The data being used as input to the digest can be modified
by using a regular expression-based substitution operation,
so that any Version Control System identifiers can be normalised
before being digested.
If no substitution regular expression is provided,
the input data will be used as-is.
.Pp
The list of digests provided is:
.Bd -literal -offset indent
BLAKE2
CRC32C
MD5
RMD160
SHA1
SHA256
SHA3-224
SHA3-256
SHA3-384
SHA3-512
SHA512
SIZE
TIGER2
TIGER
WHIRLPOOL
.Ed
.Pp
In addition, a number of hash combiner functions are defined:
.Bd -literal -offset indent
CONCAT
HASH
XOR
COMB4P
.Ed
.Pp
The
.Dv crc32c
checksum is a simple, lightweight checksum, as found in SCTP and iSCSI.
It is useful since there are times when a secure digest is not needed,
but rather an indication of correct transmission, where calculating a heavyweight
digest may be overkill.
The
.Dv TIGER2
digest is different to the
.Dv TIGER
digest in its initialisation only.
Obviously, different values are calculated for the two digests.
The
.Dv BLAKE2
digest is one of the losing finalists in the SHA-3
competition.
The winning SHA-3 contender, the sponge function
.Dv Keccak ,
has been
included here, with 4 different digest lengths, of 224, 256, 384 and 512 bits.
The
.Dv size
pseudo-algorithm simply prints the size of the input data in bytes.
.Pp
As the
.Nm
name suggests, multiple digests can be used to calculate compound digests.
The output from each digest is concatenated on the output.
Digest names are provided to the initialisation function in a comma-separated
list of names.
.Pp
The combiner functions define how the individual digests will be combined
in the finalisation stage.
They have different qualities, and different uses.
.Pp
The
.Dq CONCAT
algorithm, the default, simply concatenates the digests in the output.
It is useful when collision resistance is needed, but not pre-image resistance,
second pre-image resistance or PRF functionality.
.Pp
The
.Dq Comb4P
combiner should be used when collision resistance is needed,
or as a PRF, where target-collision resistance is needed, or
as a MAC.
However, this combiner is not as efficient as the other combiner algorithms,
requiring more CPU cycles.
.Pp
The
.Dq XOR
combiner xors the first two digests together.
This is useful as a PRF, but not where
collision resistance is needed.
.Pp
Finally, the
.Dq HASH
combiner takes the output of the second digest's
finalisation routine, and passes that as an update to the current state of
the first digest, and then finalises the multigest.
This is useful where pre-image resistance is needed,
but should not be used if collision resistance is needed.
.Pp
If less than two digest algorithms are provided in conjunction
with a combiner function, a zero multigest will result.
In addition, if the
.Dq XOR
combiner is given the same digest function as input, a zero
multigest will result.
The
.Dq Comb4P
combiner should be given two digests of the same size,
or a zero multigest will result.
.Pp
There are two interfaces to the
.Nm
library, one using the lower-level functions
.Fn multigest_init ,
.Fn multigest_update
and
.Fn multigest_final
to calculate the digests.
The other, higher-level interface,
uses the functions
.Fn mutigest_data
and
.Fn multigest_file
to operate on a complete set of bytes, or a file.
.Pp
The output from
.Fn multigest_final
is a string of unsigned bytes, which can be formatted
using
.Fn multigest_format_hex
or printed, possible to an output file, by
.Fn multigest_print_hex .
To format output without printing to a stream,
the
.Fn multigest_format_raw
function can be used.
To find out the rawsize needed (in bytes) for a multigest,
the
.Fn multigest_algs_rawsize
function can be used, passing the digest algorithm names as
arguments to the function, or the
.Fn multigest_get_rawsize
function can be used if the multigest structure has already
been initialised.
.Sh SEE ALSO
.Xr md5 3 ,
.Xr rmd160 3 ,
.Xr sha1 3 ,
.Xr sha2 3
.Sh HISTORY
The
.Nm
library first appeared in
.Nx 8.0 .
.Sh AUTHORS
.An Alistair Crooks Aq Mt agc@NetBSD.org .