well-goknown/vendor/github.com/decred/dcrd/crypto/blake256/hasher.go

416 lines
15 KiB
Go
Raw Normal View History

// Copyright (c) 2024 The Decred developers
// Use of this source code is governed by an ISC
// license that can be found in the LICENSE file.
//
// Main Go code originally written and optimized by Dave Collins May 2020.
// Additional cleanup and comments added July 2024.
// Package blake256 implements BLAKE-256 and BLAKE-224 with SSE2, SSE4.1, and
// AVX acceleration and zero allocations.
package blake256
import (
"encoding/binary"
"fmt"
"github.com/decred/dcrd/crypto/blake256/internal/compress"
)
const (
// BlockSize is the block size of the hash algorithm in bytes.
BlockSize = 64
// Size is the size of a BLAKE-256 hash in bytes.
Size = 32
// Size224 is the size of a BLAKE-224 hash in bytes.
Size224 = 28
// SavedStateSize is the number of bytes of a serialized intermediate state.
SavedStateSize = 128
)
// pad provides an efficient means to pad a message.
var pad = [64]byte{0x80}
// hasher implements a zero-allocation rolling BLAKE checksum. It can safely be
// copied at any point to save its internal state for use in additional
// processing later, without having to write the previously written data again.
//
// It contains the common logic between BLAKE-224 and BLAKE-256.
type hasher struct {
state compress.State // the current chain value and salt
count uint64 // running total of message bits hashed
buf [BlockSize]byte // partial block data buffer
nbuf uint32 // number of bytes written to data buffer
}
// makeHasher returns an instance of a rolling hasher initialized with the
// provided chain value.
func makeHasher(cv [8]uint32) hasher {
return hasher{state: compress.State{CV: cv}}
}
// reset resets the state of the rolling hash.
func (h *hasher) reset(iv [8]uint32) {
h.state.CV = iv
h.count = 0
h.nbuf = 0
}
// initializeSalt initialize the hasher state with the provided salt. Note that
// this must only be done when first creating the hasher state for correct
// results.
//
// It will panic if the provided salt is not 16 bytes.
func (h *hasher) initializeSalt(salt []byte) {
if len(salt) != 16 {
panic("salt length must be 16 bytes")
}
h.state.S[0] = binary.BigEndian.Uint32(salt)
h.state.S[1] = binary.BigEndian.Uint32(salt[4:])
h.state.S[2] = binary.BigEndian.Uint32(salt[8:])
h.state.S[3] = binary.BigEndian.Uint32(salt[12:])
}
// write adds the given bytes to the rolling hash.
//
// NOTE: This method only returns an error in order to satisfy the [io.Writer]
// and [hash.Hash] interfaces. However, it will never error, meaning the error
// will always be nil, so it is safe to ignore.
func (h *hasher) write(b []byte) (int, error) {
// All bytes will be written.
totalWritten := len(b)
// When a partial block exists and adding the new data would meet or exceed
// the size of a block, fill up the partial block and compress it.
if h.nbuf > 0 && h.nbuf+uint32(len(b)) >= BlockSize {
written := uint32(copy(h.buf[h.nbuf:], b))
h.count += BlockSize << 3
compress.Blocks(&h.state, h.buf[:], h.count)
b = b[written:]
h.nbuf = 0
}
// The previous section ensures there is no partial block data remaining.
//
// Use that fact to compress full blocks directly when the remaining number
// of bytes to write will completely fill one or more additional blocks.
//
// It is perhaps also worth noting that this approach is used over having a
// compression function that only accepts a single block because it provides
// a rather significant speed advantage on inputs that are larger than the
// size of a couple of blocks while only having a negligible impact on small
// inputs.
if len(b) >= BlockSize {
h.count += BlockSize << 3
compress.Blocks(&h.state, b, h.count)
// Update the count of message bits hashed and slice of remaining
// unwritten bytes to account for the total number of blocks compressed.
bytesHashed := uint64(len(b) &^ (BlockSize - 1))
h.count += (bytesHashed - BlockSize) << 3
b = b[bytesHashed:]
}
// Write any remaining bytes to the next partial block. Note the number of
// remaining bytes is guaranteed to be less than the size of a full block
// due to the previous sections.
if len(b) > 0 {
h.nbuf += uint32(copy(h.buf[h.nbuf:], b))
}
return totalWritten, nil
}
// writeByte adds the given byte to the rolling hash.
func (h *hasher) writeByte(b byte) {
var buf [1]byte
buf[0] = b
h.write(buf[:])
}
// writeString adds the given string to the rolling hash.
func (h *hasher) writeString(s string) {
h.write([]byte(s))
}
// writeUint16LE encodes the given unsigned 16-bit integer as a 2-byte
// little-endian byte sequence and adds it to the rolling hash.
func (h *hasher) writeUint16LE(v uint16) {
var buf [2]byte
binary.LittleEndian.PutUint16(buf[:], v)
h.write(buf[:])
}
// writeUint16BE encodes the given unsigned 16-bit integer as a 2-byte
// big-endian byte sequence and adds it to the rolling hash.
func (h *hasher) writeUint16BE(v uint16) {
var buf [2]byte
binary.BigEndian.PutUint16(buf[:], v)
h.write(buf[:])
}
// writeUint32LE encodes the given unsigned 32-bit integer as a 4-byte
// little-endian byte sequence and adds it to the rolling hash.
func (h *hasher) writeUint32LE(v uint32) {
var buf [4]byte
binary.LittleEndian.PutUint32(buf[:], v)
h.write(buf[:])
}
// writeUint32BE encodes the given unsigned 32-bit integer as a 4-byte
// big-endian byte sequence and adds it to the rolling hash.
func (h *hasher) writeUint32BE(v uint32) {
var buf [4]byte
binary.BigEndian.PutUint32(buf[:], v)
h.write(buf[:])
}
// writeUint64LE encodes the given unsigned 64-bit integer as an 8-byte
// little-endian byte sequence and adds it to the rolling hash.
func (h *hasher) writeUint64LE(v uint64) {
var buf [8]byte
binary.LittleEndian.PutUint64(buf[:], v)
h.write(buf[:])
}
// writeUint64BE encodes the given unsigned 64-bit integer as an 8-byte
// big-endian byte sequence and adds it to the rolling hash.
func (h *hasher) writeUint64BE(v uint64) {
var buf [8]byte
binary.BigEndian.PutUint64(buf[:], v)
h.write(buf[:])
}
// finalize finalizes of the rolling hash by writing any remaining partial block
// data and appending the necessary padding.
//
// The hasher may no longer be used after invoking this method. Callers always
// run finalize on a copy of the hasher so the original hasher state is not
// modified.
//
// The length preamble bit MUST be 0 (for BLAKE-224) or 1 (for BLAKE-256).
func (h *hasher) finalize(lenPreambleBit uint8) {
// Hashing a message consists of padding the message to a multiple of the
// block size and processing it block per block by the compression function.
//
// Padding the message consists of first extending the message so that its
// bit length is congruent to 447 modulo 512 by appending a 1 bit followed
// by enough 0s to reach the required congruence. Then a length preamble
// bit is added (1 for BLAKE-256, 0 for BLAKE-224) followed by the length
// of original message encoded as a 64-bit unsigned big-endian integer.
// This ensures the message length is a multiple of the block size since
// 447+1+64 = 512.
//
// Note that a special case occurs when the final block contains no original
// message bit. In that case, the message bit counter provided to the
// compression function is set to zero for that final block. This
// guarantees unique blocks.
//
// This implementation performs iterated hashing by compressing full blocks
// as data is written and storing the resulting chain value, total number of
// message bits compressed, and any remaining partial block data in the
// state.
//
// Thus, finalization consists of writing any remaining partial block data
// that hasn't already been compressed and padding the message out per the
// above.
//
// Since this implementation only allows writing full 8-bit bytes at a time,
// the following is optimized to only consider message bit lengths that are
// multiples of 8. Concretely, note that floor(447/8) = 55. Therefore, as
// long as the remaining partial block data is <= 55, only one compression
// is needed. Otherwise a second compression is needed.
msgBitLen := h.count + uint64(h.nbuf)<<3
switch {
// Exactly one padding byte is needed.
case h.nbuf == 55:
h.buf[55] = 0x80 | lenPreambleBit
binary.BigEndian.PutUint64(h.buf[56:], msgBitLen)
compress.Blocks(&h.state, h.buf[:], msgBitLen)
return
// Appending the padding to the remaining partial block data will fit
// without needing another block.
case h.nbuf < 55:
copy(h.buf[h.nbuf:55], pad[:])
h.buf[55] = lenPreambleBit
binary.BigEndian.PutUint64(h.buf[56:], msgBitLen)
// Per the specification, the counter is set to zero for the final
// compression when the final block contains no bits from the original
// message.
if h.nbuf == 0 {
msgBitLen = 0
}
compress.Blocks(&h.state, h.buf[:], msgBitLen)
return
}
// The partial block data plus the padding and message bit length exceed the
// size of a block, so two compressions are needed where the second one is
// a padding block (all zeros except for the final 8 bytes which house the
// original message length encoded as a 64-bit unsigned big-endian integer).
// Pad the remaining partial block data and compress it.
copy(h.buf[h.nbuf:], pad[:])
compress.Blocks(&h.state, h.buf[:], msgBitLen)
// Create the final padding block and compress it.
//
// Note that since the padding block does not contain any bits from the
// original message, the counter is set to zero when performing compression
// per the specification.
copy(h.buf[:], pad[1:56])
h.buf[55] = lenPreambleBit
binary.BigEndian.PutUint64(h.buf[56:], msgBitLen)
compress.Blocks(&h.state, h.buf[:], 0)
}
// wordsToBytes224 converts an array of 8 32-bit unsigned big-endian words to an
// array of 28 bytes. The final word is truncated.
func wordsToBytes224(cv [8]uint32) (out [28]byte) {
binary.BigEndian.PutUint32(out[24:], cv[6])
binary.BigEndian.PutUint32(out[20:], cv[5])
binary.BigEndian.PutUint32(out[16:], cv[4])
binary.BigEndian.PutUint32(out[12:], cv[3])
binary.BigEndian.PutUint32(out[8:], cv[2])
binary.BigEndian.PutUint32(out[4:], cv[1])
binary.BigEndian.PutUint32(out[0:], cv[0])
return out
}
// finalize224 finalizes of the rolling hash by writing any remaining partial
// block data and appending the necessary padding for BLAKE-224.
//
// The hasher may no longer be used after invoking this method. Callers always
// run finalize on a copy of the hasher so the original hasher state is not
// modified.
func (h *hasher) finalize224() [Size224]byte {
const lenPreambleBit = 0x00
h.finalize(lenPreambleBit)
return wordsToBytes224(h.state.CV)
}
// wordsToBytes256 converts an array of 8 32-bit unsigned big-endian words to an
// array of 32 bytes.
func wordsToBytes256(cv [8]uint32) (out [32]byte) {
binary.BigEndian.PutUint32(out[28:], cv[7])
binary.BigEndian.PutUint32(out[24:], cv[6])
binary.BigEndian.PutUint32(out[20:], cv[5])
binary.BigEndian.PutUint32(out[16:], cv[4])
binary.BigEndian.PutUint32(out[12:], cv[3])
binary.BigEndian.PutUint32(out[8:], cv[2])
binary.BigEndian.PutUint32(out[4:], cv[1])
binary.BigEndian.PutUint32(out[0:], cv[0])
return out
}
// finalize256 finalizes of the rolling hash by writing any remaining partial
// block data and appending the necessary padding for BLAKE-256.
//
// The hasher may no longer be used after invoking this method. Callers always
// run finalize on a copy of the hasher so the original hasher state is not
// modified.
func (h *hasher) finalize256() [Size]byte {
const lenPreambleBit = 0x01
h.finalize(lenPreambleBit)
return wordsToBytes256(h.state.CV)
}
// putSavedState serializes the intermediate state directly into the passed byte
// slice. The target slice MUST have at least [SavedStateSize] bytes available
// or it will panic.
func (h *hasher) putSavedState(target []byte, prefix uint32) {
var offset uint32
binary.BigEndian.PutUint32(target[offset:], prefix)
offset += 4
for _, cv := range h.state.CV {
binary.BigEndian.PutUint32(target[offset:], cv)
offset += 4
}
for _, s := range h.state.S {
binary.BigEndian.PutUint32(target[offset:], s)
offset += 4
}
binary.BigEndian.PutUint64(target[offset:], h.count)
offset += 8
offset += uint32(copy(target[offset:], h.buf[:]))
binary.BigEndian.PutUint32(target[offset:], h.nbuf)
}
// saveState appends the current intermediate state of the rolling hash prefixed
// by the passed value to the provided slice and returns the resulting slice.
// It does not change the underlying hash state.
//
// The provided prefix is expected to either be [statePrefix224] or
// [statePrefix256] depending on which hash variant is being saved.
//
// As described by the [hasher] documentation, the hasher instance can simply be
// copied to achieve the same result much more efficiently when the caller is
// able to keep a copy. Therefore, that approach should be preferred when
// possible.
//
// However, the ability to serialize the state is also provided to enable
// sharing it across process boundaries.
func (h *hasher) saveState(target []byte, prefix uint32) []byte {
// Create a new array and append it to the target when there is not enough
// space remaining in the slice. Otherwise, write directly into it.
//
// Note that this could alternatively just grow the slice if needed and then
// write directly into it unconditionally, but this approach is faster for
// the two much more common cases of the caller providing a slice that is
// already big enough or a nil slice.
if needed := SavedStateSize - (cap(target) - len(target)); needed > 0 {
var state [SavedStateSize]byte
h.putSavedState(state[:], prefix)
return append(target, state[:]...)
}
h.putSavedState(target[len(target):len(target)+SavedStateSize], prefix)
return target[:len(target)+SavedStateSize]
}
// loadState restores the rolling hash to the provided serialized intermediate
// state. See [hasher.saveState] for more details.
//
// The provided prefix is expected to either be [statePrefix224] or
// [statePrefix256] depending on which hash variant is being loaded.
//
// [ErrMalformedState] will be returned when the provided serialized state is
// not at least the required [SavedStateSize] number of bytes.
//
// [ErrMismatchedState] will be returned if the prefix in the serialized state
// does not match the given required prefix.
func (h *hasher) loadState(state []byte, requiredPrefix uint32) error {
if len(state) < SavedStateSize {
str := fmt.Sprintf("malformed intermediate state - must be at least "+
"%d bytes", SavedStateSize)
return makeError(ErrMalformedState, str)
}
var offset uint32
if pre := binary.BigEndian.Uint32(state[offset:]); pre != requiredPrefix {
hashType := "BLAKE-256"
if requiredPrefix != statePrefix256 {
hashType = "BLAKE-224"
}
str := fmt.Sprintf("the provided intermediate state is not for %s",
hashType)
return makeError(ErrMismatchedState, str)
}
offset += 4
for i := range h.state.CV {
h.state.CV[i] = binary.BigEndian.Uint32(state[offset:])
offset += 4
}
for i := range h.state.S {
h.state.S[i] = binary.BigEndian.Uint32(state[offset:])
offset += 4
}
h.count = binary.BigEndian.Uint64(state[offset:])
offset += 8
offset += uint32(copy(h.buf[:], state[offset:]))
h.nbuf = binary.BigEndian.Uint32(state[offset:])
return nil
}