Copyright	(c) Leo D 2023
License	BSD-3-Clause
Maintainer	leo@apotheca.io
Stability	experimental
Portability	POSIX
Safe Haskell	Safe-Inferred
Language	Haskell2010

Botan.Bindings.MAC

Description

A Message Authentication Code algorithm computes a tag over a message utilizing a shared secret key. Thus a valid tag confirms the authenticity and integrity of the message. Only entities in possession of the shared secret key are able to verify the tag.

Note

When combining a MAC with unauthenticated encryption mode, prefer to first encrypt the message and then MAC the ciphertext. The alternative is to MAC the plaintext, which depending on exact usage can suffer serious security issues. For a detailed discussion of this issue see the paper “The Order of Encryption and Authentication for Protecting Communications” by Hugo Krawczyk

The Botan MAC computation is split into five stages.

Instantiate the MAC algorithm.
Set the secret key.
Process IV.
Process data.
Finalize the MAC computation.

Synopsis

data BotanMACStruct
newtype BotanMAC = MkBotanMAC {
- runBotanMAC :: Ptr BotanMACStruct
}
botan_mac_destroy :: FinalizerPtr BotanMACStruct
pattern BOTAN_MAC_CMAC :: (Eq a, IsString a) => a
pattern BOTAN_MAC_GMAC :: (Eq a, IsString a) => a
pattern BOTAN_MAC_HMAC :: (Eq a, IsString a) => a
pattern BOTAN_MAC_Poly1305 :: (Eq a, IsString a) => a
pattern BOTAN_MAC_SipHash :: (Eq a, IsString a) => a
pattern BOTAN_MAC_X9_19_MAC :: (Eq a, IsString a) => a
botan_mac_init :: Ptr BotanMAC -> ConstPtr CChar -> Word32 -> IO CInt
botan_mac_output_length :: BotanMAC -> Ptr CSize -> IO CInt
botan_mac_set_key :: BotanMAC -> ConstPtr Word8 -> CSize -> IO CInt
botan_mac_set_nonce :: BotanMAC -> ConstPtr Word8 -> CSize -> IO CInt
botan_mac_update :: BotanMAC -> ConstPtr Word8 -> CSize -> IO CInt
botan_mac_final :: BotanMAC -> Ptr Word8 -> IO CInt
botan_mac_clear :: BotanMAC -> IO CInt
botan_mac_name :: BotanMAC -> Ptr CChar -> Ptr CSize -> IO CInt
botan_mac_get_keyspec :: BotanMAC -> Ptr CSize -> Ptr CSize -> Ptr CSize -> IO CInt

Documentation

data BotanMACStruct Source #

Opaque MAC struct

newtype BotanMAC Source #

Botan MAC object

Constructors

MkBotanMAC
Fields runBotanMAC :: Ptr BotanMACStruct

Instances

Instances details

Storable BotanMAC Source #
Instance details Defined in Botan.Bindings.MAC Methods sizeOf :: BotanMAC -> Int # alignment :: BotanMAC -> Int # peekElemOff :: Ptr BotanMAC -> Int -> IO BotanMAC # pokeElemOff :: Ptr BotanMAC -> Int -> BotanMAC -> IO () # peekByteOff :: Ptr b -> Int -> IO BotanMAC # pokeByteOff :: Ptr b -> Int -> BotanMAC -> IO () # peek :: Ptr BotanMAC -> IO BotanMAC # poke :: Ptr BotanMAC -> BotanMAC -> IO () #
Eq BotanMAC Source #
Instance details Defined in Botan.Bindings.MAC Methods (==) :: BotanMAC -> BotanMAC -> Bool # (/=) :: BotanMAC -> BotanMAC -> Bool #
Ord BotanMAC Source #
Instance details Defined in Botan.Bindings.MAC Methods compare :: BotanMAC -> BotanMAC -> Ordering # (<) :: BotanMAC -> BotanMAC -> Bool # (<=) :: BotanMAC -> BotanMAC -> Bool # (>) :: BotanMAC -> BotanMAC -> Bool # (>=) :: BotanMAC -> BotanMAC -> Bool # max :: BotanMAC -> BotanMAC -> BotanMAC # min :: BotanMAC -> BotanMAC -> BotanMAC #

botan_mac_destroy :: FinalizerPtr BotanMACStruct Source #

Frees all resources of the MAC object

pattern BOTAN_MAC_CMAC :: (Eq a, IsString a) => a Source #

pattern BOTAN_MAC_GMAC :: (Eq a, IsString a) => a Source #

pattern BOTAN_MAC_HMAC :: (Eq a, IsString a) => a Source #

pattern BOTAN_MAC_Poly1305 :: (Eq a, IsString a) => a Source #

pattern BOTAN_MAC_SipHash :: (Eq a, IsString a) => a Source #

pattern BOTAN_MAC_X9_19_MAC :: (Eq a, IsString a) => a Source #

botan_mac_init Source #

Arguments

:: Ptr BotanMAC	mac: mac object
-> ConstPtr CChar	mac_name: name of the hash function, e.g., "HMAC(SHA-384)"
-> Word32	flags: should be 0 in current API revision, all other uses are reserved and return a negative value (error code)
-> IO CInt	0 on success, a negative value on failure

Initialize a message authentication code object

botan_mac_output_length Source #

Arguments

:: BotanMAC	mac: mac object
-> Ptr CSize	output_length: output buffer to hold the MAC output length
-> IO CInt	0 on success, a negative value on failure

Writes the output length of the message authentication code to *output_length

botan_mac_set_key Source #

Arguments

:: BotanMAC	mac: mac object
-> ConstPtr Word8	key: buffer holding the key
-> CSize	key_len: size of the key buffer in bytes
-> IO CInt	0 on success, a negative value on failure

Sets the key on the MAC

botan_mac_set_nonce Source #

Arguments

:: BotanMAC	mac: mac object
-> ConstPtr Word8	nonce: buffer holding the nonce
-> CSize	nonce_len: size of the nonce buffer in bytes
-> IO CInt	0 on success, a negative value on failure

Sets the nonce on the MAC

botan_mac_update Source #

Arguments

:: BotanMAC	mac: mac object
-> ConstPtr Word8	buf: input buffer
-> CSize	len: number of bytes to read from the input buffer
-> IO CInt	0 on success, a negative value on failure

Send more input to the message authentication code

botan_mac_final Source #

Arguments

:: BotanMAC	mac: mac object
-> Ptr Word8	out[]: output buffer
-> IO CInt	0 on success, a negative value on failure

Finalizes the MAC computation and writes the output to out[0:botan_mac_output_length()] then reinitializes for computing another MAC as if botan_mac_clear had been called.

botan_mac_clear Source #

Arguments

:: BotanMAC	mac: mac object
-> IO CInt	0 on success, a negative value on failure

Reinitializes the state of the MAC computation. A MAC can be computed (with update/final) immediately.

botan_mac_name Source #

Arguments

:: BotanMAC	mac: the object to read
-> Ptr CChar	name: output buffer
-> Ptr CSize	name_len: on input, the length of buffer, on success the number of bytes written
-> IO CInt	0 on success, a negative value on failure

Get the name of this MAC

botan_mac_get_keyspec Source #

Arguments

:: BotanMAC	mac: the object to read
-> Ptr CSize	out_minimum_keylength: if non-NULL, will be set to minimum keylength of MAC
-> Ptr CSize	out_maximum_keylength: if non-NULL, will be set to maximum keylength of MAC
-> Ptr CSize	out_keylength_modulo: if non-NULL will be set to byte multiple of valid keys
-> IO CInt	0 on success, a negative value on failure

Get the key length limits of this auth code