Sel.HMAC.SHA512

Introduction

The authenticate function computes an authentication tag for a message and a secret key, and provides a way to verify that a given tag is valid for a given message and a key.

The function computing the tag deterministic: the same (message, key) tuple will always produce the same output. However, even if the message is public, knowing the key is required in order to be able to compute a valid tag. Therefore, the key should remain confidential. The tag, however, can be public.

Usage

import Sel.HMAC.SHA512 qualified as HMAC

main = do
  -- The parties agree on a shared secret key
  authKey <- HMAC.newAuthenticationKey
  -- An authentication tag is computed for the message by the server
  let message = ("Hello, world!" :: StrictByteString)
  tag <- HMAC.authenticate message
  -- The server sends the message and its authentication tag
  -- […]
  -- The recipient of the message uses the shared secret to validate the message's tag
  HMAC.verify tag authKey message
  -- => True

Operations

Authenticating a single messsage

authenticate

Arguments

:: StrictByteString

Message to authenticate

-> AuthenticationKey

Secret key for authentication

-> IO AuthenticationTag

Cryptographic tag for authentication

Compute an authentication tag for a message with a secret key shared by all parties.

Since: 0.0.1.0

Authenticating a multi-part message

data Multipart s

Multipart is a cryptographic context for streaming hashing. This API can be used when a message is too big to fit in memory or when the message is received in portions.

Use it like this:

>>> secretKey <- HMAC.newSecreKey
>>> hash <- HMAC.withMultipart secretKey $ \multipartState -> do -- we are in MonadIO
...   message1 <- getMessage
...   HMAC.updateMultipart multipartState message1
...   message2 <- getMessage
...   HMAC.updateMultipart multipartState message2

Since: 0.0.1.0

withMultipart

Arguments

:: forall (a :: Type) (m :: Type -> Type). MonadIO m

=> AuthenticationKey

-> (forall s. Multipart s -> m a)

Continuation that gives you access to a Multipart cryptographic context

-> m AuthenticationTag

Perform streaming hashing with a Multipart cryptographic context.

Use updateMultipart within the continuation.

The context is safely allocated first, then the continuation is run and then it is deallocated after that.

Since: 0.0.1.0

updateMultipart :: Multipart s -> StrictByteString -> IO ()

Add a message portion to be hashed.

This function should be used within withMultipart.

Since: 0.0.1.0

Verifying a message

verify :: AuthenticationTag -> AuthenticationKey -> StrictByteString -> Bool

Verify that the tag is valid for the provided message and secret key.

Since: 0.0.1.0

Authentication key

data AuthenticationKey

A secret authentication key of size cryptoAuthHMACSHA512Bytes.

Since: 0.0.1.0

Instances

Show AuthenticationKey

show authenticationKey == "[REDACTED]"

Since: 0.0.1.0

Defined in Sel.HMAC.SHA512

Methods

showsPrec :: Int -> AuthenticationKey -> ShowS

show :: AuthenticationKey -> String

showList :: [AuthenticationKey] -> ShowS

Eq AuthenticationKey

Since: 0.0.1.0

Defined in Sel.HMAC.SHA512

Methods

(==) :: AuthenticationKey -> AuthenticationKey -> Bool

(/=) :: AuthenticationKey -> AuthenticationKey -> Bool

Ord AuthenticationKey

Since: 0.0.1.0

Defined in Sel.HMAC.SHA512

Methods

compare :: AuthenticationKey -> AuthenticationKey -> Ordering

(<) :: AuthenticationKey -> AuthenticationKey -> Bool

(<=) :: AuthenticationKey -> AuthenticationKey -> Bool

(>) :: AuthenticationKey -> AuthenticationKey -> Bool

(>=) :: AuthenticationKey -> AuthenticationKey -> Bool

max :: AuthenticationKey -> AuthenticationKey -> AuthenticationKey

min :: AuthenticationKey -> AuthenticationKey -> AuthenticationKey

Display AuthenticationKey

display authenticatonKey == "[REDACTED]"

Since: 0.0.1.0

Defined in Sel.HMAC.SHA512

Methods

displayBuilder :: AuthenticationKey -> Builder

displayList :: [AuthenticationKey] -> Builder

displayPrec :: Int -> AuthenticationKey -> Builder

newAuthenticationKey :: IO AuthenticationKey

Generate a new random secret key of size cryptoAuthHMACSHA512KeyBytes.

Since: 0.0.1.0

authenticationKeyFromHexByteString :: StrictByteString -> Either Text AuthenticationKey

Create an AuthenticationKey from a binary StrictByteString that you have obtained on your own, usually from the network or disk.

The input secret key, once decoded from base16, must be of length cryptoAuthHMACSHA512Bytes.

Since: 0.0.1.0

unsafeAuthenticationKeyToHexByteString :: AuthenticationKey -> StrictByteString

Convert a 'AuthenticationKey to a hexadecimal-encoded StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

unsafeAuthenticationKeyToBinary :: AuthenticationKey -> StrictByteString

Convert a 'AuthenticationKey to a hexadecimal-encoded StrictByteString.

This format is useful if you need conversion to base32 or base64.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

Authentication tag

data AuthenticationTag

A secret authentication key of size cryptoAuthHMACSHA512Bytes.

Since: 0.0.1.0

Instances

Show AuthenticationTag

Since: 0.0.1.0

Defined in Sel.HMAC.SHA512

Methods

showsPrec :: Int -> AuthenticationTag -> ShowS

show :: AuthenticationTag -> String

showList :: [AuthenticationTag] -> ShowS

Eq AuthenticationTag

Since: 0.0.1.0

Defined in Sel.HMAC.SHA512

Methods

(==) :: AuthenticationTag -> AuthenticationTag -> Bool

(/=) :: AuthenticationTag -> AuthenticationTag -> Bool

Ord AuthenticationTag

Since: 0.0.1.0

Defined in Sel.HMAC.SHA512

Methods

compare :: AuthenticationTag -> AuthenticationTag -> Ordering

(<) :: AuthenticationTag -> AuthenticationTag -> Bool

(<=) :: AuthenticationTag -> AuthenticationTag -> Bool

(>) :: AuthenticationTag -> AuthenticationTag -> Bool

(>=) :: AuthenticationTag -> AuthenticationTag -> Bool

max :: AuthenticationTag -> AuthenticationTag -> AuthenticationTag

min :: AuthenticationTag -> AuthenticationTag -> AuthenticationTag

Display AuthenticationTag

Since: 0.0.1.0

Defined in Sel.HMAC.SHA512

Methods

displayBuilder :: AuthenticationTag -> Builder

displayList :: [AuthenticationTag] -> Builder

displayPrec :: Int -> AuthenticationTag -> Builder

authenticationTagToHexByteString :: AuthenticationTag -> StrictByteString

Convert an AuthenticationTag to a hexadecimal-encoded StrictByteString.

Since: 0.0.1.0

authenticationTagToBinary :: AuthenticationTag -> StrictByteString

Convert an AuthenticationTag to a binary StrictByteString.

Since: 0.0.1.0

authenticationTagFromHexByteString :: StrictByteString -> Either Text AuthenticationTag

Create an AuthenticationTag from a binary StrictByteString that you have obtained on your own, usually from the network or disk.

The input secret key, once decoded from base16, must be of length cryptoAuthHMACSHA512Bytes.

Since: 0.0.1.0