sel-0.0.1.0: Cryptography for the casual user
MaintainerThe Haskell Cryptography Group
PortabilityGHC only
Safe HaskellSafe-Inferred
LanguageHaskell2010

Sel.HMAC.SHA512_256

Description

 
Synopsis

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_256 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 Source #

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 Source #

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 Source #

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 () Source #

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 Source #

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

Since: 0.0.1.0

Authentication key

newAuthenticationKey :: IO AuthenticationKey Source #

Generate a new random secret key of size cryptoAuthHMACSHA512256KeyBytes.

Since: 0.0.1.0

authenticationKeyFromHexByteString :: StrictByteString -> Either Text AuthenticationKey Source #

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 cryptoAuthHMACSHA512256Bytes.

Since: 0.0.1.0

unsafeAuthenticationKeyToHexByteString :: AuthenticationKey -> StrictByteString Source #

Convert a 'AuthenticationKey to a hexadecimal-encoded StrictByteString.

⚠️ Be prudent as to where you store it!

Since: 0.0.1.0

unsafeAuthenticationKeyToBinary :: AuthenticationKey -> StrictByteString Source #

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

authenticationTagFromHexByteString :: StrictByteString -> Either Text AuthenticationTag Source #

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 cryptoAuthHMACSHA512256Bytes.

Since: 0.0.1.0