skein

Documentation

Overview

This package implements the Skein hash and Skein MAC algorithms as defined if the Skein V1.3 specification. Skein is one of the five SHA-3 candidate algorithms that advance to the third (and final) round of the SHA-3 selection.

The implementation in this package supports:

• All three state sizes of Skein and Threefish: 256, 512, and 1024 bits
• Skein MAC
• Variable length of hash and MAC input and output - even in numbers of bits
• Full message length as defined in the Skein paper (2^96 -1 bytes, not just a meager 4 GiB :-) )
• Tested with the official test vectors that are part of the NIST CD (except Tree hashes)

The implementation does not support tree hashing.

Copyright (C) 2011 Werner Dittmann

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Authors: Werner Dittmann <Werner.Dittmann@t-online.de>

Copyright (C) 2011 Werner Dittmann

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Authors: Werner Dittmann <Werner.Dittmann@t-online.de>

Copyright (C) 2011 Werner Dittmann

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Authors: Werner Dittmann <Werner.Dittmann@t-online.de>

Index

• Constants
• func New256() hash.Hash
• type Skein
  • func New(stateSize, outputSize int) (*Skein, error)
  • func NewExtended(stateSize, outputSize, treeInfo int, key []byte) (*Skein, error)
  • func (s *Skein) BlockSize() int
  • func (s *Skein) DoFinal() (hash []byte)
  • func (s *Skein) Reset()
  • func (s *Skein) Size() int
  • func (s *Skein) Sum(b []byte) []byte
  • func (s *Skein) Update(input []byte)
  • func (s *Skein) UpdateBits(input []byte, numBits int) error
  • func (s *Skein) Write(p []byte) (nn int, err error)
• type SkeinMac
  • func NewMac(stateSize, outputSize int, key []byte) (s *SkeinMac, err error)
  • func (s *SkeinMac) DoFinal() (hash []byte)
  • func (s *SkeinMac) Reset()
  • func (s *SkeinMac) Update(input []byte)
  • func (s *SkeinMac) UpdateBits(input []byte, numBits int) error

Constants

const (
	Skein256  = 256
	Skein512  = 512
	Skein1024 = 1024
)

const (
	Key             int = 0
	Config          int = 4
	Personalization int = 8
	PublicKey       int = 12
	KeyIdentifier   int = 16
	Nonce           int = 20
	Message         int = 48
	Out             int = 63
)

Functions

func New256

func New256() hash.Hash

Create a new Skein hash instance - 256bit (32 byte) hash size. This Skein hash uses the 512bit state length

Types

type Skein

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

func New

func New(stateSize, outputSize int) (*Skein, error)

Initializes the Skein hash instance.

stateSize

The Skein state size of the hash in bits. Supported values
are 256, 512, and 1024

outputSize

The output size of the hash in bits. Output size must greater
than zero.

func NewExtended

func NewExtended(stateSize, outputSize, treeInfo int, key []byte) (*Skein, error)

Initializes the Skein hash instance for use with a key and tree.

stateSize

The internal state size of the hash in bits. Supported values
are 256, 512, and 1024

outputSize

The output size of the hash in bits. Output size must greater
than zero.

treeInfo

Not yet supported.

key

The key for a message authenication code (MAC)

func (*Skein) BlockSize

func (s *Skein) BlockSize() int

BlockSize returns the hash's underlying block size. The Write method must be able to accept any amount of data, but it may operate more efficiently if all writes are a multiple of the block size.

func (*Skein) DoFinal

func (s *Skein) DoFinal() (hash []byte)

Finalize Skein digest and return the hash.

This method resets the Skein digest after it computed the digest. An application may reuse this Skein context to compute another digest.

func (*Skein) Reset

func (s *Skein) Reset()

Reset resets the hash to one with zero bytes written.

func (*Skein) Size

func (s *Skein) Size() int

Size return the hash size in bytes if the hash size measured in bits is a multiple of 8.

If the bit size is not a multiple of 8 then Size returns 0.

func (*Skein) Sum

func (s *Skein) Sum(b []byte) []byte

Sum returns the current hash, without changing the underlying hash state. TODO: discuss if this makes sense for Skein - Skein works with 64bit int internally

func (*Skein) Update

func (s *Skein) Update(input []byte)

Update Skein digest with the next part of the message.

input

Byte slice that contains data to hash.

func (*Skein) UpdateBits

func (s *Skein) UpdateBits(input []byte, numBits int) error

Update the hash with a message bit string.

Skein can handle data not only as bytes but also as bit strings of arbitrary length (up to its maximum design size).

array

The byte array that holds the bit string. The array must be big
enough to hold all bits.

numBits

Number of bits to hash.

func (*Skein) Write

func (s *Skein) Write(p []byte) (nn int, err error)

Write adds more data to the current hash. It never returns an error.

In this implementation it's just a thin wrapper and calls Update()

type SkeinMac

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

func NewMac

func NewMac(stateSize, outputSize int, key []byte) (s *SkeinMac, err error)

Initializes a Skein MAC context.

Initializes the context with this data and saves the resulting Skein state variables for further use.

Applications call the normal Skein functions to update the MAC and get the final result.

stateSize

Which Skein state size to use. Supported values
are 256, 512, and 1024

outputSize

Number of MAC hash bits to compute

key

The key bytes

func (*SkeinMac) DoFinal

func (s *SkeinMac) DoFinal() (hash []byte)

Finalize Skein MAC and return the hash.

This method resets the Skein MAC after it computed the MAC. An application may reuse this Skein MAC context to compute another MAC with the same key and sizes.

func (*SkeinMac) Reset

func (s *SkeinMac) Reset()

Resets a Skein context for further use.

Restores the saved chaining variables to reset the Skein context. Thus applications can reuse the same setup to process several messages. This saves a complete Skein initialization cycle.

func (*SkeinMac) Update

func (s *SkeinMac) Update(input []byte)

Update Skein MAC with the next part of the message.

input

Byte slice that contains data to hash.

func (*SkeinMac) UpdateBits

func (s *SkeinMac) UpdateBits(input []byte, numBits int) error

Update the MAC with a message bit string.

Skein can handle data not only as bytes but also as bit strings of arbitrary length (up to its maximum design size).

input

Byte slice that contains data to hash. The length of the byte slice
must match the formula: (numBits + 7) / 8.

numBits

Number of bits to hash.