raaz-0.2.3: The raaz cryptographic library.
Safe HaskellNone
LanguageHaskell2010

Raaz.Hash.Internal

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

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.

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.

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

Instances

Instances details
Describable (HashI h m) Source # 
Instance details

Defined in Raaz.Hash.Internal

Methods

name :: HashI h m -> String Source #

description :: HashI h m -> String Source #

BlockAlgorithm (HashI h m) Source # 
Instance details

Defined in Raaz.Hash.Internal

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

forall m.HashM h m => SomeHashI (HashI h m) 

Instances

Instances details
Describable (SomeHashI h) Source # 
Instance details

Defined in Raaz.Hash.Internal

BlockAlgorithm (SomeHashI h) Source # 
Instance details

Defined in Raaz.Hash.Internal

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

Instances

Instances details
Storable h => Memory (HashMemory h) Source # 
Instance details

Defined in Raaz.Hash.Internal

Storable h => Extractable (HashMemory h) h Source # 
Instance details

Defined in Raaz.Hash.Internal

Methods

extract :: MT (HashMemory h) h Source #

Storable h => Initialisable (HashMemory h) h Source # 
Instance details

Defined in Raaz.Hash.Internal

Methods

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

Initialisable (HashMemory SHA1) () Source # 
Instance details

Defined in Raaz.Hash.Sha1.Internal

Methods

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

Initialisable (HashMemory SHA256) () Source # 
Instance details

Defined in Raaz.Hash.Sha256.Internal

Methods

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

Initialisable (HashMemory SHA512) () Source # 
Instance details

Defined in Raaz.Hash.Sha512.Internal

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