skids/perl6sum/lib/Sum/MDPad
perl6sum src
NAME
Sum::MDPad
SYNOPSIS
use Sum::MDPad;
role mySum does Sum::MDPad[:blocksize(1024)] does Sum::Marshal::Raw {...}
DESCRIPTION
Support code for common Merkle-Damgård-compliant padding schemes
ROLES
(head2) role Sum::MDPad [ :$blocksize, :$lengthtype, :$overflow, :@firstpad ]
does Sum {
The C<Sum::MDPad> parametric role defines an interface and shared
code which is useful for types of C<Sum> which use prevalent variations
of Merkle-Damgård-compliant padding. This is a system for breaking
to-be-hashed messages up into blocks. It defines a format used in
the last blocks, which contain the remainder of the message, a
pad marker, padding, and a message length field.
The role parameter C<:blocksize> sets the size of message blocks in
bits. The C<:firstpad> parameter specifies a bit pattern appended
to the message before zero-padding. Currently this must be an Array
of Bool values, and defaults to C<[True]>, which causes one set bit
to be appended before padding the unused portion of the last block
with clear bits.
The C<:lengthtype> and C<:overflow> parameters control the format
and behavior of the length counter and are described with the relevant
methods below.
(head2) method pos
The C<Sum::MDPad> role handles the C<.pos> method, keeping track of how
many bits of message have been provided to the sum. The C<:lengthtype>
role parameter determines how it is stored in the padding. Until sized
unsigned types are available, it should be set to the string "uint64_be"
or the string "uint64_le" to specify storage in big-endian or
little-endian format, respectively, or for 128-bit lengths, "uint128_be"
or "uint128_le". These are the only four formats currently supported.
The C<:overflow> role attribute specifies whether the sum should fail
if a message larger than the C<:lengthtype> can express is provided,
or simply truncate higher bits off the length counter when storing it
in the final block. The default is C<True>, the latter, which is
relatively benign with large counter sizes. The option is mainly provided
for strict specification compliance, and will rarely be relevant in
common usage scenarios.
(head2) method elems
The C<Sum::MDPad> role handles the C<.elems> method, which also
has units of bits. Immediately after a sum is created, but before
supplying addends, this method may be used as an lvalue to set an
expected (nonzero) size for the message. The behavior in this case
is as described in the C<Sum> base interface.
If not set explicitly, this method simply returns the same value as
the C<.pos> method.
(head2) method pos_block_inc
The C<!pos_block_inc> method should be called by the C<.add>
multi-candidate which handles complete blocks, in order to update
the message bit count. This will be a private method which only
composers may use, but is currently public (C<.pos_block_inc>).
It automatically handles finagling the count on the last blocks,
so from the composer's side it should simply be called once for
each full block processed. It also automatically handles checking
for extra addends pushed to a finalized sum, and for length
violations when C<.elems> has been explicity set to a nonzero value.
As such any failures returned should abort the sum and be returned
directly.
(head2) multi method add
The C<Sum::MDPad> role provides multi candidates for the C<.add>
method which handle erroneous addends, missing addends, and short
blocks. The algorithm-specific code which mixes in C<Sum::MDPad>
need only provide a single additional candidate which processes
one complete block of message.
The resulting C<Sum> expects single blocks as addends. Currently,
that means a C<Buf> with C<blocksize/8> elements. Passing a shorter
C<Buf> with C<0..^blocksize/8> elements may be done once, before or
during finalization. Such a short C<Buf> may optionally be followed
by up to 7 bits (currently, 7 xx Bool) if the message does not end on a
byte boundary. Attempts to provide more blocks after passing a short
block will result in an C<X::Sum::Final>.
Note that C<.add> does not handle slurpy argument lists, and when
using C<Sum::Marshal::Raw>, one call to C<.push> should be made per
block. Slurpy lists may be C<.push>ed if C<Sum::Marshal::Block> roles
are mixed instead.
AUTHOR
Written by Brian S. Julin
COPYRIGHT
Copyright (c) 2012 Brian S. Julin. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the terms
of the Perl Artistic License 2.0.
REFERENCES
SEE ALSO
C<Sum::(pm3)>
