Using this module

Currently this module provides both Skein as a cryptographic
hash function and Skein as a MAC. This module currently does
not provide some Skein functions, such as tree hashing,
pseudo-random number generation, stream ciphing or key
derivation.

Terminology note: we say "message" for your variable-sized
data that is given to Skein.

Skein as a cryptographic hash function

There are many variants of Skein as a cryptographic hash
function. They are called Skein_X_Y, where X is internal
state size in bits and Y is the output size in bits. The
main ones are Skein_512_512, Skein_1024_1024 and
Skein_256_256. If you are unsure, then use Skein_512_512.

To use these data types, you have to use Hash and
Serialize. Suppose you wanted to hash a lazy ByteStringbs. Then you could use

Skein as a message authentication code (MAC)

If you need a message authentication code (MAC), you may use
HMAC with Skein (e.g. HMAC-Skein-512-512). Using HMAC with
Skein is supported and secure. However, Skein also supports
another secure method, called Skein-MAC.

Skein-MAC is as secure as HMAC with Skein, however with a much
lower overhead (especially for short messages). HMAC requires
two hash invocations. Skein-MAC, on the other hand, requires
just one hash invocation after the setup.

To use Skein-MAC, you need skeinMAC (or skeinMAC') and
Serialize. You also need a Key with at least as many bits
as the state size you choose (256, 512 or 1024 bits).

Suppose you want to use Skein-MAC with Skein_512_512. To
setup the MAC function with a Keykey (that has at least
512 / 8 = 64 bytes), use

About Skein

Skein is a new family of cryptographic hash functions. Its
design combines speed, security, simplicity, and a great deal
of flexibility in a modular package that is easy to analyze.

Skein is fast. Skein-512 -- our primary proposal -- hashes data at
6.1 clock cycles per byte on a 64-bit CPU. This means that on
a 3.1 GHz x64 Core 2 Duo CPU, Skein hashes data at 500
MBytes/second per core -- almost twice as fast as SHA-512 and
three times faster than SHA-256. An optional hash-tree mode
speeds up parallelizable implementations even more. Skein is
fast for short messages, too; Skein-512 hashes short messages
in about 1000 clock cycles.

Skein is secure. Our current best attack on Skein-512 is on 25
of 72 rounds, for a safety factor of 2.9. For comparison, at a
similar stage in the standardization process, the AES
encryption algorithm had an attack on 6 of 10 rounds, for a
safety factor of only 1.7. Additionally, Skein has a number of
provably secure properties, increasing confidence in the
algorithm.

Skein is simple. Using only three primitive operations, the
Skein compression function can be easily understood and
remembered. The rest of the algorithm is a straightforward
iteration of this function.

Skein is flexible. Skein is defined for three different
internal state sizes -- 256 bits, 512 bits, and 1024 bits --
and any output size. This allows Skein to be a drop-in
replacement for the entire SHA family of hash functions. A
completely optional and extendable argument system makes Skein
an efficient tool to use for a very large number of functions:
a PRNG, a stream cipher, a key derivation function,
authentication without the overhead of HMAC, and a
personalization capability. All these features can be
implemented with very low overhead. Together with the
Threefish large-block cipher at Skein core, this design
provides a full set of symmetric cryptographic primitives
suitable for most modern applications.

Skein is efficient on a variety of platforms, both hardware
and software. Skein-512 can be implemented in about 200 bytes
of state. Small devices, such as 8-bit smart cards, can
implement Skein-256 using about 100 bytes of memory. Larger
devices can implement the larger versions of Skein to achieve
faster speeds.

Skein was designed by a team of highly experienced
cryptographic experts from academia and industry, with
expertise in cryptography, security analysis, software, chip
design, and implementation of real-world cryptographic
systems. This breadth of knowledge allowed them to create a
balanced design that works well in all environments.

Main cryptographic hash functions

These are the main Skein hash functions. Unless you have any
special reasons, you should use one of these.

is the low-memory variant. It can be
implemented using 100 bytes of RAM, but this is not the case
with this implementation. It is faster than Skein_512_512
only for small message lengths, so it's preferable to use
Skein_512_512. If you can't afford 512 bits of output,
you may get the speed advantage of Skein_512_512 by using
Skein_512_256.

Skein-1024-1024

Skein-1024-1024 hash. You probably want to use encode to
obtain a 1024-bit (128-byte) ByteString. This is the
ultra-conservative variant. Even if some future attack
managed to break Skein-512, it's quite likely that Skein-1024
would remain secure.

Skein-MAC

The standard way to use a hash function for authentication is
to use the HMAC construction. While you may securely use
Skein with HMAC (e.g. HMAC-Skein-512-512), Skein also supports
another mode for MAC. Skein-MAC is as secure as
HMAC-Skein, however faster. Skein-MAC is as fast as
Skein as a hash function, with zero overhead.

The Key may have any length. However, it's recommended to
have at least the same number of bits of the state size. For
example, when using skeinMAC with Skein_512_256, it is
recommended to have a key with at least 64 bytes (512 bits),
which is the state size of Skein_512_256 (the first of the
two numbers).

Class of Skein contexts that may be used for Skein-MAC (all
of them). Included here mostly for documentation purposes,
since adding new instances is not safe (functions using
SkeinMAC unsurprisingly assume that they are using Skein).

Other variants of cryptographic hash functions

These hash functions produce less output bits than their state
size. For example, Skein_512_160 produces 160 output bits
while having 512 bits of state size. Their main use is to be
a drop-in replacement to legacy hash functions. If you don't
have any special reason for using them, use one of the main
hash functions above (e.g. Skein_512_512).