raaz-0.1.1: The raaz cryptographic library.

Safe Haskell | None
Language | Haskell2010

Raaz.Hash.Internal

Contents

- Cryptographic hashes and their implementations.
  - Computing hashes using non-standard implementations.
- Hash implementations.
  - Implementation of truncated hashes.
- Memory used by most hashes.
- Some low level functions.

Description

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.

Synopsis

- class (Primitive h, EndianStore h, Encodable h, Eq h, Implementation h ~ SomeHashI h) => Hash h where
- hash :: (Hash h, Recommendation h, PureByteSource src) => src -> h
- hashFile :: (Hash h, Recommendation h) => FilePath -> IO h
- hashSource :: (Hash h, Recommendation h, ByteSource src) => src -> IO h
- hash' :: (PureByteSource src, Hash h) => Implementation h -> src -> h
- hashFile' :: Hash h => Implementation h -> FilePath -> IO h
- hashSource' :: (Hash h, ByteSource src) => Implementation h -> src -> IO h
- data HashI h m = HashI {
  - hashIName :: String
  - hashIDescription :: String
  - compress :: Pointer -> BLOCKS h -> MT m ()
  - compressFinal :: Pointer -> BYTES Int -> MT m ()
  - compressStartAlignment :: Alignment
  }
- data SomeHashI h = HashM h m => SomeHashI (HashI h m)
- type HashM h m = (Initialisable m (), Extractable m h, Primitive h)
- truncatedI :: (BLOCKS htrunc -> BLOCKS h) -> (mtrunc -> m) -> HashI h m -> HashI htrunc mtrunc
- data HashMemory h = HashMemory {
  - hashCell :: MemoryCell h
  - messageLengthCell :: MemoryCell (BITS Word64)
  }
- extractLength :: MT (HashMemory h) (BITS Word64)
- updateLength :: LengthUnit u => u -> MT (HashMemory h) ()
- completeHashing :: (Hash h, ByteSource src, HashM h m) => HashI h m -> src -> MT m h

# 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 Source #

Type class capturing a cryptographic hash.

Minimal complete definition

additionalPadBlocks

Methods

additionalPadBlocks :: h -> BLOCKS h Source #

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 Source # |
Methods additionalPadBlocks :: SHA1 -> BLOCKS SHA1 Source #
Hash SHA224 Source # |
Methods additionalPadBlocks :: SHA224 -> BLOCKS SHA224 Source #
Hash SHA256 Source # |
Methods additionalPadBlocks :: SHA256 -> BLOCKS SHA256 Source #
Hash SHA384 Source # |
Methods additionalPadBlocks :: SHA384 -> BLOCKS SHA384 Source #
Hash SHA512 Source # |
Methods additionalPadBlocks :: SHA512 -> BLOCKS SHA512 Source #

hash Source #

Arguments

:: (Hash h, Recommendation h, PureByteSource src) |
=> src | Message
-> h |

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

hashFile Source #

Arguments

:: (Hash h, Recommendation h) |
=> FilePath | File to be hashed
-> IO h |

Compute the hash of file.

hashSource Source #

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' Source #

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' Source #

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 Source #

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

# Hash implementations.

data HashI h m Source #

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) Source # |
Methods name :: HashI h m -> String Source # description :: HashI h m -> String Source #
BlockAlgorithm (HashI h m) Source # |
Methods bufferStartAlignment :: HashI h m -> Alignment Source #

data SomeHashI h Source #

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) Source # |
Methods name :: SomeHashI h -> String Source # description :: SomeHashI h -> String Source #
BlockAlgorithm (SomeHashI h) Source # |
Methods bufferStartAlignment :: SomeHashI h -> Alignment Source #

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

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 Source #

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 Source #

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) Source # |
Methods memoryAlloc :: Alloc (HashMemory h) Source # unsafeToPointer :: HashMemory h -> Pointer Source #
Storable h => Extractable (HashMemory h) h Source # |
Methods extract :: MT (HashMemory h) h Source #
Storable h => Initialisable (HashMemory h) h Source # |
Methods initialise :: h -> MT (HashMemory h) () Source #
Initialisable (HashMemory SHA1) () Source # |
Methods initialise :: () -> MT (HashMemory SHA1) () Source #
Initialisable (HashMemory SHA256) () Source # |
Methods initialise :: () -> MT (HashMemory SHA256) () Source #
Initialisable (HashMemory SHA512) () Source # |
Methods initialise :: () -> MT (HashMemory SHA512) () Source #

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

Extract the length of the message hashed so far.

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

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 Source #

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).