LIBMULTIGEST(3)

NAME
libmultigest - Multiple digest library

LIBRARY
libmultigest

SYNOPSIS
#include <multigest.h>
multigest_t *
multigest_new(void);
int
multigest_init(multigest_t *mg, const char *algorithms);
int
multigest_add_subst(multigest_t *mg, const char *substregex, const char *replacement);
void
multigest_update(multigest_t *mg, const void *data, size_t length);
void
multigest_final(unsigned char *rawdigest, multigest_t *mg);
uint8_t *
multigest_data(const char *algorithms, const void *data, size_t length, const unsigned char *rawoutput, const char *substregex, const char *replacement);
uint8_t *
multigest_file(const char *algorithms, const char *filename, const unsigned char *rawoutput, const char *substregex, const char *replacement);
uint32_t
multigest_get_rawsize(multigest_t *mg);
uint32_t
multigest_algs_rawsize(const char *algnames);
int
multigest_format_hex(unsigned char *rawinput, const char *algorithms, char *output, size_t outputsize);
int
multigest_print_hex(unsigned char *rawinput, const char *algorithms, const char *outname, const char *filename, const char *substregex, const char *output_separator, const char *output_format);
char *
multigest_format_raw(const uint8_t *rawinput, size_t insize, char *fmtoutput, size_t outsize);

DESCRIPTION
libmultigest 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.

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.

The list of digests provided is:

    BLAKE2
    CRC32C
    MD5
    RMD160
    SHA1
    SHA256
    SHA3-224
    SHA3-256
    SHA3-384
    SHA3-512
    SHA512
    SIZE
    TIGER2
    TIGER
    WHIRLPOOL

In addition, a number of hash combiner functions are defined:

    CONCAT
    HASH
    XOR
    COMB4P

The 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 TIGER2 digest is different to the TIGER digest in its initialisation only. Obviously, different values are calculated for the two digests. The BLAKE2 digest is one of the losing finalists in the SHA-3 competition. The winning SHA-3 contender, the sponge function Keccak, has been included here, with 4 different digest lengths, of 224, 256, 384 and 512 bits. The size pseudo-algorithm simply prints the size of the input data in bytes.

As the libmultigest 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.

The combiner functions define how the individual digests will be combined in the finalisation stage. They have different qualities, and different uses.

The “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.

The “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.

The “XOR” combiner xors the first two digests together. This is useful as a PRF, but not where collision resistance is needed.

Finally, the “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.

If less than two digest algorithms are provided in conjunction with a combiner function, a zero multigest will result. In addition, if the “XOR” combiner is given the same digest function as input, a zero multigest will result. The “Comb4P” combiner should be given two digests of the same size, or a zero multigest will result.

There are two interfaces to the libmultigest library, one using the lower-level functions multigest_init(), multigest_update() and multigest_final() to calculate the digests. The other, higher-level interface, uses the functions mutigest_data() and multigest_file() to operate on a complete set of bytes, or a file.

The output from multigest_final() is a string of unsigned bytes, which can be formatted using multigest_format_hex() or printed, possible to an output file, by multigest_print_hex(). To format output without printing to a stream, the multigest_format_raw() function can be used. To find out the rawsize needed (in bytes) for a multigest, the multigest_algs_rawsize() function can be used, passing the digest algorithm names as arguments to the function, or the multigest_get_rawsize() function can be used if the multigest structure has already been initialised.

SEE ALSO
md5(3), rmd160(3), sha1(3), sha2(3)

HISTORY
The libmultigest library first appeared in NetBSD 8.0.

AUTHORS
Alistair Crooks <agc@NetBSD.org>.