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
- additionalPadBlocks :: h -> BLOCKS h
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 = forall m.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:

Define a new type which captures the result of hashing. This type should be an instance of the class Hash.
Define an implementation, i.e. a value of the type SomeHashI.
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.

Instances

Instances details

Hash BLAKE2s Source #
Instance details Defined in Raaz.Hash.Blake2.Internal Methods additionalPadBlocks :: BLAKE2s -> BLOCKS BLAKE2s Source #
Hash BLAKE2b Source #
Instance details Defined in Raaz.Hash.Blake2.Internal Methods additionalPadBlocks :: BLAKE2b -> BLOCKS BLAKE2b Source #
Hash SHA1 Source #
Instance details Defined in Raaz.Hash.Sha1.Internal Methods additionalPadBlocks :: SHA1 -> BLOCKS SHA1 Source #
Hash SHA224 Source #
Instance details Defined in Raaz.Hash.Sha224.Internal Methods additionalPadBlocks :: SHA224 -> BLOCKS SHA224 Source #
Hash SHA256 Source #
Instance details Defined in Raaz.Hash.Sha256.Internal Methods additionalPadBlocks :: SHA256 -> BLOCKS SHA256 Source #
Hash SHA384 Source #
Instance details Defined in Raaz.Hash.Sha384.Internal Methods additionalPadBlocks :: SHA384 -> BLOCKS SHA384 Source #
Hash SHA512 Source #
Instance details Defined in Raaz.Hash.Sha512.Internal 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.

The action compress impl ptr blks should only read till the blks offset starting at ptr and never write any data.
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

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

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

Instances

Instances details

Describable (SomeHashI h) Source #
Instance details Defined in Raaz.Hash.Internal Methods name :: SomeHashI h -> String Source # description :: SomeHashI h -> String Source #
BlockAlgorithm (SomeHashI h) Source #
Instance details Defined in Raaz.Hash.Internal 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

Instances details

Storable h => Memory (HashMemory h) Source #
Instance details Defined in Raaz.Hash.Internal Methods memoryAlloc :: Alloc (HashMemory h) Source # unsafeToPointer :: HashMemory h -> Pointer Source #
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).