OpenSSL.EVP.Digest

Low-level bindings to OpenSSL's EVP interface. Most users do not need this code. Check out OpenSSL.Digest for a more comfortable interface.

Digest Algorithms

data Algorithm

An opaque handle into OpenSSL's collection of message digest algorithms. Use digestByName to look up any of the available algorithms by name. For the sake of convenience, Algorithm is an instance of IsString so that the compiler can transparently map String literals to algorithms via fromString if the XOverloadedStrings extension is enabled.

>>> fromString "sha256" == digestByName "sha256"
True

Instances

Eq Algorithm

Methods

(==) :: Algorithm -> Algorithm -> Bool

(/=) :: Algorithm -> Algorithm -> Bool

Show Algorithm

Methods

showsPrec :: Int -> Algorithm -> ShowS

show :: Algorithm -> String

showList :: [Algorithm] -> ShowS

IsString Algorithm

Methods

fromString :: String -> Algorithm

digestByName :: String -> Algorithm

Look up a digest algorithm engine by name. Algorithms usually offered by OpenSSL are "md2", "md5", "sha1", "mdc2", "ripemd160", "blake2b512", "blake2s256", "sha224", "sha256", "sha384", and "sha512", but the exact set may vary between platforms. Throws UnknownAlgorithm if the requested algorithm is not known.

digestByName' :: String -> Maybe Algorithm

Variant of digestByName that signals failure by evaluating to Nothing rather than failing.

>>> digestByName' "sha256" == Just (digestByName "sha256")
True
>>> digestByName' "Guess what?" :: Maybe Algorithm
Nothing

digestSize :: Algorithm -> Int

Return the size of the digest in bytes that the given algorithm will produce.

>>> digestSize (digestByName "sha256")
32

maxDigestSize :: Int

The largest possible digest size of any of the algorithms supported by this library will generate. So if you want to store a digest without bothering to retrieve the appropriate size with digestSize first, allocate a buffer of that size.

digestBlockSize :: Algorithm -> Int

Return the block size the the given algorithm operates with.

>>> digestBlockSize (digestByName "sha256")
64

data UnknownAlgorithm

A custom exception type which is thrown by digestByName in case the requested digest algorithm is not available in the OpenSSL system library.

Instances

Show UnknownAlgorithm

Methods

showsPrec :: Int -> UnknownAlgorithm -> ShowS

show :: UnknownAlgorithm -> String

showList :: [UnknownAlgorithm] -> ShowS

Exception UnknownAlgorithm

Methods

toException :: UnknownAlgorithm -> SomeException

fromException :: SomeException -> Maybe UnknownAlgorithm

displayException :: UnknownAlgorithm -> String

Digest Contexts

data Context

A context for digest computations. Use newContext and freeContext to allocate/deallocate this type.

Instances

Eq Context

Methods

(==) :: Context -> Context -> Bool

(/=) :: Context -> Context -> Bool

Show Context

Methods

showsPrec :: Int -> Context -> ShowS

show :: Context -> String

showList :: [Context] -> ShowS

newContext :: IO Context

Allocate and initialize an Context for use in a digest computation on the heap. Release its underlying memory after use with freeContext.

freeContext :: Context -> IO ()

Release all resources associated with a digest computation.

resetDigest :: Context -> IO ()

Free all resources associated with this Context, but don't destroy the context itself so that it can be re-used for a new digest computation.

Digest Computations

initDigest :: Algorithm -> Context -> IO ()

Configure the given digest context to use the given message digest algorithm. Throws an exception to signal failure, i.e. because the system is out of memory.

updateDigest :: Context -> Ptr a -> CSize -> IO ()

Hash the given block of memory and update the digest state accordingly. This function can be called many times. Then use finalizeDigest to retrieve the actual hash value.

finalizeDigest :: Context -> Ptr Word8 -> IO ()

Finalize the digest calculation and return the result in the Word8 array passed as an argument. Naturally, that array is expected to be large enough to contain the digest. digestSize or maxDigestSize are your friends. This function does not clean up the digest context; this has to be done with an explicit call to freeContext (or resetContext, if you want to re-use it). However, it does invalidate the digest state so that no further calls of digestUpdate can be made without re-initializing the context first.