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 char *data, size_t length);
void
multigest_final(unsigned char *rawdigest, multigest_t *mg);
uint8_t *
multigest_data(const char *algorithms, const char *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

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.

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 7.0.

AUTHORS
Alistair Crooks <agc@NetBSD.org>.