polyval

README

polyval

This module implements POLYVAL per RFC 8452.

The universal hash function POLYVAL is the byte-wise reverse of GHASH.

Installation

go get github.com/ericlagergren/polyval@latest

Performance

The x86-64 and ARMv8 assembly backends run at about 0.25 cycles per byte. The x86-64 implementation requires SSE2 and PCLMULQDQ instructions. The ARMv8 implementation requires NEON and PMULL.

The default Go implementation will be selected if the CPU does not support either assembly implementation. (This implementation can also be selected with the purego build tag.) It is much slower at around 9 cycles per byte.

Security

Disclosure

This project uses full disclosure. If you find a security bug in an implementation, please e-mail me or create a GitHub issue.

Disclaimer

You should only use cryptography libraries that have been reviewed by cryptographers or cryptography engineers. While I am a cryptography engineer, I'm not your cryptography engineer, and I have not had this project reviewed by any other cryptographers.

Documentation

Overview

Package polyval implements POLYVAL per RFC 8452.

The universal hash function POLYVAL is the byte-wise reverse of GHASH.

Index

• Constants
• func Sum(key, data []byte) [Size]byte
• type Polyval
  • func New(key []byte) (*Polyval, error)
  • func (p *Polyval) BlockSize() int
  • func (p *Polyval) Init(key []byte) error
  • func (p *Polyval) MarshalBinary() ([]byte, error)
  • func (p *Polyval) Reset()
  • func (p *Polyval) Size() int
  • func (p *Polyval) Sum(b []byte) []byte
  • func (p *Polyval) UnmarshalBinary(data []byte) error
  • func (p *Polyval) Update(blocks []byte)

Constants

const (
	// Size is the size in bytes of a POLYVAL checksum.
	Size = 16
)

Functions

func Sum

func Sum(key, data []byte) [Size]byte

Sum returns the POLYVAL hash of data.

Types

type Polyval

type Polyval struct {
	// contains filtered or unexported fields
}

Polyval is an implementation of POLYVAL.

It operates similar to the standard library's Hash interface, but only accepts full blocks. Callers should pad the input accordingly.

POLYVAL is similar to GHASH. It operates in GF(2^128) defined by the irreducible polynomial

x^128 + x^127 + x^126 + x^121 + 1.

The field has characteristic 2, so addition is performed with XOR. Multiplication is polynomial multiplication reduced modulo the polynomial.

For more information on POLYVAL, see [rfc8452].

func New

func New(key []byte) (*Polyval, error)

New creates a Polyval.

The key must be exactly 16 bytes long and cannot be all zero.

func (*Polyval) BlockSize

func (p *Polyval) BlockSize() int

BlockSize returns the size of a POLYVAL block.

func (*Polyval) Init

func (p *Polyval) Init(key []byte) error

Init initializes a Polyval.

The key must be exactly 16 bytes long and cannot be all zero.

func (*Polyval) MarshalBinary

func (p *Polyval) MarshalBinary() ([]byte, error)

MarshalBinary implements BinaryMarshaler.

It does not return an error.

func (*Polyval) Reset

func (p *Polyval) Reset()

Reset sets the hash to its original state.

func (*Polyval) Size

func (p *Polyval) Size() int

Size returns the size of a POLYVAL digest.

func (*Polyval) Sum

func (p *Polyval) Sum(b []byte) []byte

Sum appends the current hash to b and returns the resulting slice.

It does not change the underlying hash state.

func (*Polyval) UnmarshalBinary

func (p *Polyval) UnmarshalBinary(data []byte) error

Unmarshalbinary implements BinaryUnmarshaler.

data must be exactly 160 bytes.

func (*Polyval) Update

func (p *Polyval) Update(blocks []byte)

Update writes one or more blocks to the running hash.

If len(block) is not divisible by BlockSize, Update will panic.