Raaz.Hash.Internal

This module exposes the low-level internal details of cryptographic hashes. Do not import this module unless you want to implement a new hash or give a new implementation of an existing hash.

Cryptographic hashes and their implementations.

Each cryptographic hash is a distinct type and are instances of a the type class Hash. The standard idiom that we follow for hash implementations are the following:

HashI:

This type captures implementations of a the hash. This type is parameterised over the memory element used by the implementation.

SomeHashI:

This type is the existentially quantified version of HashI over its memory element. Thus it exposes only the interface and not the internals of the implementation. The Implementation associated type of a hash is the type SomeHashI

To support a new hash, a developer needs to:

1. Define a new type which captures the result of hashing. This type should be an instance of the class Hash.
2. Define an implementation, i.e. a value of the type SomeHashI.
3. Define a recommended implementation, i.e. an instance of the type class Recommendation

class (Primitive h, EndianStore h, Encodable h, Eq h, Implementation h ~ SomeHashI h) => Hash h where

Type class capturing a cryptographic hash.

Minimal complete definition

additionalPadBlocks

Methods

additionalPadBlocks :: h -> BLOCKS h

Cryptographic hashes can be computed for messages that are not a multiple of the block size. This combinator computes the maximum size of padding that can be attached to a message.

Instances

Hash SHA1

Methods

additionalPadBlocks :: SHA1 -> BLOCKS SHA1

Hash SHA224

Methods

additionalPadBlocks :: SHA224 -> BLOCKS SHA224

Hash SHA256

Methods

additionalPadBlocks :: SHA256 -> BLOCKS SHA256

Hash SHA384

Methods

additionalPadBlocks :: SHA384 -> BLOCKS SHA384

Hash SHA512

Methods

additionalPadBlocks :: SHA512 -> BLOCKS SHA512

hash

Arguments

:: (Hash h, Recommendation h, PureByteSource src)

=> src

Message

-> h

Compute the hash of a pure byte source like, ByteString.

hashFile

Arguments

:: (Hash h, Recommendation h)

=> FilePath

File to be hashed

-> IO h

Compute the hash of file.

hashSource

Arguments

:: (Hash h, Recommendation h, ByteSource src)

=> src

Message

-> IO h

Compute the hash of a generic byte source.

Computing hashes using non-standard implementations.

hash'

Arguments

:: (PureByteSource src, Hash h)

=> Implementation h

Implementation

-> src

the message as a byte source.

-> h

Similar to hash but the user can specify the implementation to use.

hashFile'

Arguments

:: Hash h

=> Implementation h

Implementation

-> FilePath

File to be hashed

-> IO h

Similar to hashFile' but the user can specify the implementation to use.

hashSource' :: (Hash h, ByteSource src) => Implementation h -> src -> IO h

Similar to hashSource but the user can specify the implementation to use.

Hash implementations.

data HashI h m

The Hash implementation. Implementations should ensure the following.

1. The action compress impl ptr blks should only read till the blks offset starting at ptr and never write any data.
2. The action padFinal impl ptr byts should touch at most ⌈byts/blocksize⌉ + padBlocks blocks starting at ptr. It should not write anything till the byts offset but may write stuff beyond that.

An easy to remember this rule is to remember that computing hash of a payload should not modify the payload.

Constructors

HashI

Fields

• hashIName :: String
• hashIDescription :: String
• compress :: Pointer -> BLOCKS h -> MT m ()

  compress the blocks,

• compressFinal :: Pointer -> BYTES Int -> MT m ()

  pad and process the final bytes,

• compressStartAlignment :: Alignment

Instances

Describable (HashI h m)

Methods

name :: HashI h m -> String

description :: HashI h m -> String

BlockAlgorithm (HashI h m)

Methods

bufferStartAlignment :: HashI h m -> Alignment

data SomeHashI h

Some implementation of a given hash. The existentially quantification allows us freedom to choose the best memory type suitable for each implementations.

Constructors

HashM h m => SomeHashI (HashI h m)

Instances

Describable (SomeHashI h)

Methods

name :: SomeHashI h -> String

description :: SomeHashI h -> String

BlockAlgorithm (SomeHashI h)

Methods

bufferStartAlignment :: SomeHashI h -> Alignment

type HashM h m = (Initialisable m (), Extractable m h, Primitive h)

The constraints that a memory used by a hash implementation should satisfy.

Implementation of truncated hashes.

truncatedI :: (BLOCKS htrunc -> BLOCKS h) -> (mtrunc -> m) -> HashI h m -> HashI htrunc mtrunc

Certain hashes are essentially bit-truncated versions of other hashes. For example, SHA224 is obtained from SHA256 by dropping the last 32-bits. This combinator can be used build an implementation of truncated hash from the implementation of its parent hash.

Memory used by most hashes.

data HashMemory h

Computing cryptographic hashes usually involves chunking the message into blocks and compressing one block at a time. Usually this compression makes use of the hash of the previous block and the length of the message seen so far to compressing the current block. Most implementations therefore need to keep track of only hash and the length of the message seen so. This memory can be used in such situations.

Constructors

HashMemory

Fields

• hashCell :: MemoryCell h

  Cell to store the hash

• messageLengthCell :: MemoryCell (BITS Word64)

  Cell to store the length

Instances

Storable h => Memory (HashMemory h)

Methods

memoryAlloc :: Alloc (HashMemory h)

unsafeToPointer :: HashMemory h -> Pointer

Storable h => Extractable (HashMemory h) h

Methods

extract :: MT (HashMemory h) h

Storable h => Initialisable (HashMemory h) h

Methods

initialise :: h -> MT (HashMemory h) ()

Initialisable (HashMemory SHA1) ()

Methods

initialise :: () -> MT (HashMemory SHA1) ()

Initialisable (HashMemory SHA256) ()

Methods

initialise :: () -> MT (HashMemory SHA256) ()

Initialisable (HashMemory SHA512) ()

Methods

initialise :: () -> MT (HashMemory SHA512) ()

extractLength :: MT (HashMemory h) (BITS Word64)

Extract the length of the message hashed so far.

updateLength :: LengthUnit u => u -> MT (HashMemory h) ()

Update the message length by a given amount.

Some low level functions.

completeHashing :: (Hash h, ByteSource src, HashM h m) => HashI h m -> src -> MT m h

Gives a memory action that completes the hashing procedure with the rest of the source. Useful to compute the hash of a source with some prefix (like in the HMAC procedure).