Copyright	(C) Hécate Moonlight 2022
License	BSD-3-Clause
Maintainer	The Haskell Cryptography Group
Stability	Stable
Portability	GHC only
Safe Haskell	Trustworthy
Language	Haskell2010

LibSodium.Bindings.GenericHashing

Contents

Introduction
Operations
Constants

Description

Synopsis

data CryptoGenericHashState
cryptoGenericHash :: Ptr CUChar -> CSize -> Ptr CUChar -> CULLong -> Ptr CUChar -> CSize -> IO CInt
cryptoGenericHashKeyGen :: Ptr CUChar -> IO ()
withGenericHashState :: (Ptr CryptoGenericHashState -> IO a) -> IO a
withGenericHashStateOfSize :: CSize -> (Ptr CryptoGenericHashState -> IO a) -> IO a
cryptoGenericHashInit :: Ptr CryptoGenericHashState -> Ptr CUChar -> CSize -> CSize -> IO CInt
cryptoGenericHashUpdate :: Ptr CryptoGenericHashState -> Ptr CUChar -> CULLong -> IO CInt
cryptoGenericHashFinal :: Ptr CryptoGenericHashState -> Ptr CUChar -> CSize -> IO CInt
cryptoGenericHashBytes :: CSize
cryptoGenericHashBytesMin :: CSize
cryptoGenericHashBytesMax :: CSize
cryptoGenericHashKeyBytes :: CSize
cryptoGenericHashKeyBytesMin :: CSize
cryptoGenericHashKeyBytesMax :: CSize
cryptoGenericHashStateBytes :: CSize

Introduction

This API computes a fixed-length fingerprint for an arbitrarily long message. It is backed by the BLAKE2b algorithm.

Sample use cases:

File integrity checking
Creating unique identifiers to index arbitrarily long data

⚠️ Do not use this API module to hash passwords!

Whenever there is a Ptr CryptoGenericHashState, it must point to enough memory to hold the hash state. This is at least cryptoGenericHashBytesMin, at most cryptoGenericHashBytesMax, and should typically be cryptoGenericHashBytes. It is the caller's responsibility to ensure that this holds.

Operations

data CryptoGenericHashState Source #

Opaque tag representing the hash state struct crypto_generichash_state used by the C API.

To use a CryptoGenericHashState, use withGenericHashState.

Since: 0.0.1.0

cryptoGenericHash Source #

Arguments

:: Ptr CUChar	`out` parameter.
-> CSize	`outlen` parameter.
-> Ptr CUChar	`in` parameter.
-> CULLong	`inlen` parameter.
-> Ptr CUChar	`key` parameter.
-> CSize	`keylen` parameter.
-> IO CInt	Returns 0 on success, -1 on error.

Put a fingerprint of the message (the in parameter) of length inlen into the out buffer. The minimum recommended output size (outlen) is cryptoGenericHashBytes. However, for specific use cases, the size can be any value between cryptoGenericHashBytesMin (included) and cryptoGenericHashBytesMax (included).

The key parameter can be nullPtr and keylen can be 0. In this case, a message will always have the same fingerprint But a key can also be specified. A message will always have the same fingerprint for a given key, but different keys used to hash the same message are very likely to produce distinct fingerprints. In particular, the key can be used to make sure that different applications generate different fingerprints even if they process the same data.

The recommended key size is cryptoGenericHashKeyBytes bytes.

However, the key size can be any value between 0 (included) and cryptoGenericHashKeyBytesMax (included). If the key is meant to be secret, the recommended minimum length is cryptoGenericHashKeyBytesMin.

See: crypto_generichash()

Since: 0.0.1.0

cryptoGenericHashKeyGen Source #

Arguments

:: Ptr CUChar	A pointer to the key
-> IO ()

This function creates a key of the recommended length cryptoGenericHashKeyBytes.

See: crypto_generichash_keygen()

Since: 0.0.1.0

withGenericHashState :: (Ptr CryptoGenericHashState -> IO a) -> IO a Source #

This function allocates a CryptoGenericHashState of size cryptoGenericHashBytes. If you want more control over the size of the hash state, use withGenericHashStateOfSize.

⚠️ Do not leak the CryptoGenericHashState outside of the lambda, otherwise you will point at deallocated memory!

Since: 0.0.1.0

withGenericHashStateOfSize :: CSize -> (Ptr CryptoGenericHashState -> IO a) -> IO a Source #

This function allocates a CryptoGenericHashState of the desired size.

Use the following constants as parameter to this function:

Since: 0.0.1.0

cryptoGenericHashInit Source #

Arguments

:: Ptr CryptoGenericHashState	Pointer to the hash state
-> Ptr CUChar	Pointer to a key
-> CSize	Length of the key
-> CSize	Length of the result
-> IO CInt	Returns 0 on success, -1 on error.

Initialise a hash state with a key of a specified length, and produce an output with the specified length in bytes.

The Ptr CUChar argument must point to enough memory to hold a key, which must also be initialised. This is at least cryptoGenericHashKeyBytesMin, at most cryptoGenericHashKeyBytesMax, and should typically be cryptoGenericHashKeyBytes. It is the caller's responsibility to ensure that these hold.

See: crypto_generichash_init()

Since: 0.0.1.0

cryptoGenericHashUpdate Source #

Arguments

:: Ptr CryptoGenericHashState	Pointer to the hash state
-> Ptr CUChar	Pointer to a chunk to be processed
-> CULLong	Length of the chunk in bytes
-> IO CInt	Returns 0 on success, -1 on error.

If you process a message in chunks, you can sequentially process each chunk by calling cryptoGenericHashUpdate by providing a pointer to the previously initialised state, a pointer to the input chunk, and the length of the chunk in bytes.

See: crypto_generichash_update()

Since: 0.0.1.0

cryptoGenericHashFinal Source #

Arguments

:: Ptr CryptoGenericHashState	The hash state used throughout the previous hashing operations.
-> Ptr CUChar	The pointer to the resulting fingerprint.
-> CSize	Size of the hash.
-> IO CInt	Returns 0 on success, -1 if called twice.