Raaz.Auth

Message authentication.

Given a message M the message authenticator computed using the key K is a short summary S of M with the additional property that it is cryptographically hard to compute S if the key K is unknown. In fact some thing stronger is true: Even when the adversary knows a set of messages M₁,...,Mₙ and their authenticators S₁,...Sₙ, all of which was created using the key K, she cannot construct a message M different from M₁,...,Mₙ and its authenticator S without knowing the key K.

In addition to proving integrity, the authenticator s proves the authenticity of the message m --- if one knows the secret K, on successful verification of the authenticator, one can be convinced that the message could only have originated from a peer who knows K.

Serialisation

Message authentication tags are instances of Encodable and hence can be serilised to byte strings.

Warning

Message authentication does not provide secrecy of the message, use encrypted authenticator instead Raaz.AuthEncrypt.

type Auth = Auth

The type of authentication tag.

auth

Arguments

:: PureByteSource src

=> Key Auth

-> src

Message

-> Auth

Compute the authenticator of a pure byte source like, ByteString.

authFile

Arguments

:: Key Auth

-> FilePath

File to be authed

-> IO Auth

Compute the authenticator for a file.

authSource :: ByteSource src => Key Auth -> src -> IO Auth

Compute the authenticator of an arbitrary byte source.

Incremental processing.

Message authenticator can also be computed incrementally using a authenticator context captured by the AuthCxt data type. The three functions relevant for this style of operation are startAuth, updateAuth, and finaliseAuth which respectively prepares the context for a new incremental processing, updates the context with an additional chunk of data, and finalises the context to recover the digest. The type AuthCxt is an instance of the class Memory and hence any IO action that requires a AuthCxt as argument can be run using the withMemory combinator.

If the entire input is with you either as a file or a string, the auth and authFile is a much more high level interface and should be preferred.

type AuthCxt = AuthCxt

The authentication context for incremental computation of auth tag.

startAuth

Arguments

:: KnownNat n

=> Key Auth

The key to be used

-> AuthCxt n

-> IO ()

Prepare the context to (re)start a session of incremental processing.

updateAuth :: (KnownNat n, ByteSource src) => src -> AuthCxt n -> IO ()

Add some more data into the context, in this case the entirety of the byte source src.

finaliseAuth :: KnownNat n => AuthCxt n -> IO Auth

Finalise the context to get hold of the digest.

Specific message authentication algorithms

If interoperability with other applications demands the use of a specific primitive for message authentication, you can use one of these more specific modules.

• Raaz.Auth.Blake2b
• Raaz.Auth.Blake2s