ShortHashing.hs

{-# LANGUAGE CApiFFI #-}

-- |
-- Module: LibSodium.Bindings.ShortHashing
-- Description: Short but unpredictable hashes based on SipHash-2-4.
-- Copyright: (C) Hécate Moonlight
-- License: BSD-3-Clause
-- Maintainer: The Haskell Cryptography Group
-- Stability: Stable
-- Portability: GHC only
--
-- The short-input hashing functions have a variety of use-cases, such as:
--
-- * Hash Tables
-- * Probabilistic data structures, such as Bloom filters
-- * Integrity checking in interactive protocols
--
-- Note however that the output of 'cryptoShortHash' is only 64 bit. Therefore, it should not be considered resistant to collisions.
--
-- The 'cryptoShortHashX24' function has a 128-bit output which is more resistant to collisions.
module LibSodium.Bindings.ShortHashing
  ( -- ** Functions
    cryptoShortHashKeyGen
  , cryptoShortHash
  , cryptoShortHashX24KeyGen
  , cryptoShortHashX24

    -- ** Constants
  , cryptoShortHashKeyBytes
  , cryptoShortHashBytes
  , cryptoShortHashSipHashX24KeyBytes
  , cryptoShortHashSipHashX24Bytes
  ) where

import Data.Word (Word8)
import Foreign.C (CInt (CInt), CSize (CSize), CUChar, CULLong (CULLong))
import Foreign.Ptr (Ptr, castPtr)

import LibSodium.Bindings.Random (randombytesBuf)

-- | Create a secret key of size 'cryptoShortHashKeyBytes'.
--
--  It is implemented by libsodium with 'randombytesBuf'
--
--  /See:/ [crypto_shorthash_keygen()](https://github.com/jedisct1/libsodium/blob/1.0.18/src/libsodium/crypto_shorthash/crypto_shorthash.c#L30-L34)
--
-- @since 0.0.1.0
foreign import capi "sodium.h crypto_shorthash_keygen"
  cryptoShortHashKeyGen
    :: Ptr CUChar
    -- ^ Buffer that will hold the secret key.
    -> IO ()

-- | Hash an input message with a secret key.
-- The secret key is of size 'cryptoShortHashKeyBytes'
-- and can be generated with 'cryptoShortHashKeyGen'.
--
-- /See:/ [crypto_shorthash()](https://doc.libsodium.org/hashing/short-input_hashing#usage)
--
-- @since 0.0.1.0
foreign import capi "sodium.h crypto_shorthash"
  cryptoShortHash
    :: Ptr CUChar
    -- ^ Buffer that will hold the fingerprint, of size 'cryptoShortHashBytes'.
    -> Ptr CUChar
    -- ^ Buffer that holds the input message.
    -> CULLong
    -- ^ Length of the input message.
    -> Ptr CUChar
    -- ^ Buffer that holds the secret key, of size 'cryptoShortHashKeyBytes'.
    -> IO CInt
    -- ^ The function returns -1 if the hashing fails and 0 on success.

-- | Create a secret key of size 'cryptoShortHashSipHashX24KeyBytes'.
--
-- It is implemented with 'randombytesBuf'
--
-- @since 0.0.1.0
cryptoShortHashX24KeyGen
  :: Ptr CUChar
  -- ^ Buffer that will hold the secret key.
  -> IO ()
cryptoShortHashX24KeyGen ptr =
  randombytesBuf (castPtr ptr :: Ptr Word8) cryptoShortHashSipHashX24KeyBytes

-- | Hash an input message with a secret key to a 128-bit fingerprint.
--
-- The secret key can be generated with 'cryptoShortHashX24KeyGen'.
--
-- /See:/ [crypto_shorthash_siphashx24()](https://github.com/jedisct1/libsodium/blob/1.0.18/src/libsodium/crypto_shorthash/siphash24/ref/shorthash_siphashx24_ref.c#L6)
--
-- @since 0.0.1.0
foreign import capi "sodium.h crypto_shorthash_siphashx24"
  cryptoShortHashX24
    :: Ptr CUChar
    -- ^ Buffer that will hold the fingerprint, of size 'cryptoShortHashSipHashX24Bytes'.
    -> Ptr CUChar
    -- ^ Buffer that holds the input message.
    -> CULLong
    -- ^ Length of the input message.
    -> Ptr CUChar
    -- ^ Buffer that holds the secret key, of size 'cryptoShortHashSipHashX24KeyBytes'.
    -> IO CInt
    -- ^ The function returns -1 if the hashing fails and 0 on success.

-- === Constants

-- | Size of the key generated by 'cryptoShortHashKeyGen'.
--
-- /See:/ [crypto_shorthash_KEYBYTES](https://doc.libsodium.org/hashing/short-input_hashing#constants)
--
-- @since 0.0.1.0
foreign import capi "sodium.h value crypto_shorthash_KEYBYTES"
  cryptoShortHashKeyBytes :: CSize

-- | Size of the fingerprint computed by 'cryptoShortHash'.
--
-- /See:/ [crypto_shorthash_BYTES](https://doc.libsodium.org/hashing/short-input_hashing#constants)
--
-- @since 0.0.1.0
foreign import capi "sodium.h value crypto_shorthash_BYTES"
  cryptoShortHashBytes :: CSize

-- | Size of the key generated by 'cryptoShortHashKeyGen'.
--
-- /See:/ [crypto_shorthash_siphashx24_BYTES](https://github.com/jedisct1/libsodium/blob/1.0.18/src/libsodium/include/sodium/crypto_shorthash_siphash24.h#LL32C9-L32C42)
--
-- @since 0.0.1.0
foreign import capi "sodium.h value crypto_shorthash_siphashx24_KEYBYTES"
  cryptoShortHashSipHashX24KeyBytes :: CSize

-- | Size of the fingerprint computed by 'cryptoShortHashX24'.
--
-- /See:/ [crypto_shorthash_siphashx24_KEYBYTES](https://github.com/jedisct1/libsodium/blob/1.0.18/src/libsodium/include/sodium/crypto_shorthash_siphash24.h#L36)
--
-- @since 0.0.1.0
foreign import capi "sodium.h value crypto_shorthash_siphashx24_BYTES"
  cryptoShortHashSipHashX24Bytes :: CSize