-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | BLAKE3 hashing algorithm
--   
--   Bindings to the official BLAKE3 implementation in C
@package blake3
@version 0.1

module BLAKE3.IO

-- | Initialize a <a>HasherInternal</a>.
init :: Ptr HasherInternal -> IO ()

-- | Update <a>HasherInternal</a> state with new data.
update :: forall bin. ByteArrayAccess bin => Ptr HasherInternal -> [bin] -> IO ()

-- | Finalize <a>HasherInternal</a> state and obtain a digest.
--   
--   The <a>HasherInternal</a> is mutated.
finalize :: forall len. KnownNat len => Ptr HasherInternal -> IO (Digest len)

-- | Immutable BLAKE3 hashing state.
--   
--   Obtain with <a>hasher</a> or <a>hasherKeyed</a>.
data Hasher

-- | Allocate <a>Hasher</a>.
--   
--   The <a>Hasher</a> is wiped and freed as soon as it becomes unused.
allocRetHasher :: forall a. (Ptr HasherInternal -> IO a) -> IO (a, Hasher)

-- | Output from BLAKE3 algorithm, of <tt>len</tt> bytes.
--   
--   The default digest length for BLAKE3 is <a>DEFAULT_DIGEST_LEN</a>.
data Digest (len :: Nat)

-- | Allocate a <a>Digest</a>.
--   
--   The <a>Digest</a> is wiped and freed as soon as it becomes unused.
allocRetDigest :: forall len a. KnownNat len => (Ptr Word8 -> IO a) -> IO (a, Digest len)

-- | Opaque datatype of size <a>HASHER_SIZE</a> and alignment
--   <a>HASHER_ALIGNMENT</a>.
--   
--   Obtain with <a>withHasherInternal</a>.
data HasherInternal

-- | Copy an inmutable <a>Hasher</a>.
copyHasher :: Hasher -> IO Hasher

-- | Mutate the given <a>Hasher</a>.
withHasherInternal :: Hasher -> (Ptr HasherInternal -> IO a) -> IO a

-- | Key used for keyed hashing mode.
--   
--   Obtain with <a>key</a>.
--   
--   See <a>hashKeyed</a>.
data Key

-- | Obtain a <a>Key</a> for use in BLAKE3 keyed hashing.
--   
--   See <a>hashKeyed</a>.
key :: ByteArrayAccess bin => bin -> Maybe Key

-- | Allocate a <a>Key</a>.
--   
--   The <a>Key</a> is wiped and freed as soon as it becomes unused.
allocRetKey :: forall a. (Ptr Word8 -> IO a) -> IO (a, Key)

-- | Initialize a <a>HasherInternal</a> in keyed mode.
initKeyed :: Ptr HasherInternal -> Key -> IO ()

-- | Context for BLAKE3 key derivation. Obtain with <a>context</a>.
data Context

-- | Obtain a <a>Context</a> for BLAKE3 key derivation.
--   
--   The context should be hardcoded, globally unique, and
--   application-specific.
--   
--   A good format for the context string is:
--   
--   <pre>
--   [application] [commit timestamp] [purpose]
--   </pre>
--   
--   For example:
--   
--   <pre>
--   example.com 2019-12-25 16:18:03 session tokens v1
--   </pre>
context :: ByteArrayAccess bin => bin -> Maybe Context

-- | Initialize a <a>HasherInternal</a> in derivation mode.
--   
--   The input key material must be provided afterwards, using
--   <a>update</a>.
initDerive :: Ptr HasherInternal -> Context -> IO ()
type HASHER_ALIGNMENT = 8

-- | In bytes.
type HASHER_SIZE = 1912

-- | In bytes.
type KEY_LEN = 32

-- | In bytes.
type BLOCK_SIZE = 64

-- | In bytes.
type DEFAULT_DIGEST_LEN = 32
instance GHC.Classes.Eq BLAKE3.IO.Context
instance Data.ByteArray.Types.ByteArrayAccess BLAKE3.IO.Key
instance GHC.Classes.Eq BLAKE3.IO.Key
instance Data.ByteArray.Types.ByteArrayAccess (BLAKE3.IO.Digest len)
instance GHC.Classes.Eq (BLAKE3.IO.Digest len)
instance GHC.Show.Show BLAKE3.IO.Context
instance Data.String.IsString BLAKE3.IO.Context
instance GHC.Show.Show BLAKE3.IO.Key
instance GHC.Show.Show (BLAKE3.IO.Digest len)


-- | Haskell bindings to the <a>official BLAKE3 hashing implementation in
--   C</a>.
--   
--   The original C implementation is released into the public domain with
--   CC0 1.0. Alternatively, it is licensed under the Apache License 2.0,
--   copyright of Jack O'Connor and Samuel Neves. See its <a>LICENSE</a>
--   for details.
--   
--   This Haskell library is the copyright of Renzo Carbonara, licensed
--   under the terms of the <a>Apache License 2.0</a>.
module BLAKE3

-- | BLAKE3 hashing.
--   
--   For incremental hashing, see <a>hasher</a>, <a>update</a> and
--   <a>finalize</a>:
--   
--   <pre>
--   <a>hash</a> = <a>finalize</a> <a>.</a> <a>update</a> <a>hasher</a>
--   </pre>
hash :: forall len bin. (KnownNat len, ByteArrayAccess bin) => [bin] -> Digest len

-- | Output from BLAKE3 algorithm, of <tt>len</tt> bytes.
--   
--   The default digest length for BLAKE3 is <a>DEFAULT_DIGEST_LEN</a>.
data Digest (len :: Nat)

-- | BLAKE3 hashing with a <a>Key</a>.
--   
--   For incremental hashing, see <a>hasherKeyed</a>, <a>update</a> and
--   <a>finalize</a>:
--   
--   <pre>
--   <a>hashKeyed</a> key = <a>finalize</a> <a>.</a> <a>update</a> (<a>hasherKeyed</a> key)
--   </pre>
hashKeyed :: forall len bin. (KnownNat len, ByteArrayAccess bin) => Key -> [bin] -> Digest len

-- | Key used for keyed hashing mode.
--   
--   Obtain with <a>key</a>.
--   
--   See <a>hashKeyed</a>.
data Key

-- | Obtain a <a>Key</a> for use in BLAKE3 keyed hashing.
--   
--   See <a>hashKeyed</a>.
key :: ByteArrayAccess bin => bin -> Maybe Key

-- | BLAKE3 key derivation.
derive :: forall len ikm. (KnownNat len, ByteArrayAccess ikm) => Context -> [ikm] -> Digest len

-- | Context for BLAKE3 key derivation. Obtain with <a>context</a>.
data Context

-- | Obtain a <a>Context</a> for BLAKE3 key derivation.
--   
--   The context should be hardcoded, globally unique, and
--   application-specific.
--   
--   A good format for the context string is:
--   
--   <pre>
--   [application] [commit timestamp] [purpose]
--   </pre>
--   
--   For example:
--   
--   <pre>
--   example.com 2019-12-25 16:18:03 session tokens v1
--   </pre>
context :: ByteArrayAccess bin => bin -> Maybe Context

-- | Immutable BLAKE3 hashing state.
--   
--   Obtain with <a>hasher</a> or <a>hasherKeyed</a>.
data Hasher

-- | Initial <a>Hasher</a> for incremental hashing.
hasher :: Hasher

-- | Initial <a>Hasher</a> for incremental <i>keyed</i> hashing.
hasherKeyed :: Key -> Hasher

-- | Update <a>Hasher</a> with new data.
update :: forall bin. ByteArrayAccess bin => Hasher -> [bin] -> Hasher

-- | Update <a>Hasher</a> with new data.
finalize :: forall len. KnownNat len => Hasher -> Digest len

-- | In bytes.
type KEY_LEN = 32

-- | In bytes.
type BLOCK_SIZE = 64

-- | In bytes.
type DEFAULT_DIGEST_LEN = 32