Botan.Low.Hash

Hash functions are one-way functions, which map data of arbitrary size to a fixed output length. Most of the hash functions in Botan are designed to be cryptographically secure, which means that it is computationally infeasible to create a collision (finding two inputs with the same hash) or preimages (given a hash output, generating an arbitrary input with the same hash). But note that not all such hash functions meet their goals, in particular MD4 and MD5 are trivially broken. However they are still included due to their wide adoption in various protocols.

Using a hash function is typically split into three stages: initialization, update, and finalization (often referred to as a IUF interface). The initialization stage is implicit: after creating a hash function object, it is ready to process data. Then update is called one or more times. Calling update several times is equivalent to calling it once with all of the arguments concatenated. After completing a hash computation (eg using hashFinal), the internal state is reset to begin hashing a new message.

Hashing

A hash is deterministic, one-way function suitable for producing a deterministic, fixed-size digest from an arbitrarily-sized message, which is used to verify the integrity of the data.

Usage

Unless you need a specific hash, it is strongly recommended that you use the SHA3 algorithm.

import Botan.Low.Hash
hash <- hashInit SHA3
message = "Fee fi fo fum!"
hashUpdate hash message
digest <- hashFinal hash

You can verify a digest by hashing the message a second time, and comparing the two:

rehash <- hashInit SHA3
hashUpdate rehash message
redigest <- hashFinal rehash
digest == redigest -- True

You can clear a hash's state, leaving it ready for reuse:

hashClear hash
-- Process another message
hashUpdate hash anotherMessage
anotherDigest <- hashFinal hash

newtype Hash

Constructors

MkHash

Fields

• getHashForeignPtr :: ForeignPtr BotanHashStruct

type HashName = ByteString

type HashDigest = ByteString

withHash :: Hash -> (BotanHash -> IO a) -> IO a

hashInit

Arguments

:: HashName

hash_name: name of the hash function, e.g., "SHA-384"

-> IO Hash

hash: hash object

hashDestroy :: Hash -> IO ()

hashName

Arguments

:: Hash

hash: the object to read

-> IO HashDigest

name: output buffer

hashBlockSize

Arguments

:: Hash

hash: hash object

-> IO Int

block_size: output buffer to hold the hash function block size

hashOutputLength

Arguments

:: Hash

hash: hash object

-> IO Int

block_size: output buffer to hold the hash function output length

hashCopyState

Arguments

:: Hash

source: source hash object

-> IO Hash

dest: destination hash object

hashUpdate

Arguments

:: Hash

hash: hash object

-> ByteString

in: input buffer

-> IO ()

hashFinal

Arguments

:: Hash

hash: hash object

-> IO HashDigest

out[]: output buffer

hashUpdateFinalize :: Hash -> ByteString -> IO HashDigest

hashUpdateFinalizeClear :: Hash -> ByteString -> IO HashDigest

hashClear

Arguments

:: Hash

hash: hash object

-> IO ()

Hash algorithms

pattern BLAKE2b :: HashName

blake2b :: (Ord a, Num a, Show a) => a -> HashName

pattern Keccak1600 :: HashName

keccak1600 :: (Eq a, Num a, Show a) => a -> HashName

pattern GOST_34_11 :: HashName

pattern MD4 :: HashName

pattern MD5 :: HashName

pattern RIPEMD160 :: HashName

pattern SHA1 :: HashName

pattern SHA224 :: HashName

pattern SHA256 :: HashName

pattern SHA384 :: HashName

pattern SHA512 :: HashName

pattern SHA512_256 :: HashName

pattern SHA3 :: HashName

sha3 :: (Eq a, Num a, Show a) => a -> HashName

pattern SHAKE128 :: HashName

shake128 :: Show a => a -> HashName

pattern SHAKE256 :: HashName

shake256 :: Show a => a -> HashName

pattern SM3 :: HashName

pattern Skein512 :: HashName

skein512 :: Show a => a -> HashName -> HashName

pattern Streebog256 :: HashName

pattern Streebog512 :: HashName

pattern Whirlpool :: HashName

pattern Parallel :: HashName

pattern Comb4P :: HashName

pattern Adler32 :: HashName

pattern CRC24 :: HashName

pattern CRC32 :: HashName

Convenience

cryptohashes :: [HashName]

checksums :: [HashName]

allHashes :: [HashName]