Module Name: othersrc
Committed By: agc
Date: Wed Mar 26 06:58:57 UTC 2014
Modified Files:
othersrc/external/bsd/multigest/dist: libmultigest.3
Log Message:
Document the digest combiner functions for libmultigest(3).
To generate a diff of this commit:
cvs rdiff -u -r1.6 -r1.7 othersrc/external/bsd/multigest/dist/libmultigest.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: othersrc/external/bsd/multigest/dist/libmultigest.3
diff -u othersrc/external/bsd/multigest/dist/libmultigest.3:1.6 othersrc/external/bsd/multigest/dist/libmultigest.3:1.7
--- othersrc/external/bsd/multigest/dist/libmultigest.3:1.6 Tue Mar 4 02:12:58 2014
+++ othersrc/external/bsd/multigest/dist/libmultigest.3 Wed Mar 26 06:58:57 2014
@@ -1,4 +1,4 @@
-.\" $NetBSD: libmultigest.3,v 1.6 2014/03/04 02:12:58 agc Exp $
+.\" $NetBSD: libmultigest.3,v 1.7 2014/03/26 06:58:57 agc Exp $
.\"
.\" Copyright (c) 2013,2014 Alistair Crooks <a...@netbsd.org>
.\" All rights reserved.
@@ -23,7 +23,7 @@
.\" (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
+.Dd March 25, 2014
.Dt LIBMULTIGEST 3
.Os
.Sh NAME
@@ -123,6 +123,14 @@ 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.
@@ -154,6 +162,49 @@ The output from each digest is concatena
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
