| Copyright | (C) Hécate Moonlight 2022 |
|---|---|
| License | BSD-3-Clause |
| Maintainer | The Haskell Cryptography Group |
| Portability | GHC only |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Sel.HMAC.SHA256
Description
Synopsis
- authenticate :: StrictByteString -> AuthenticationKey -> IO AuthenticationTag
- data Multipart s
- withMultipart :: forall (a :: Type) (m :: Type -> Type). MonadIO m => AuthenticationKey -> (forall s. Multipart s -> m a) -> m AuthenticationTag
- updateMultipart :: Multipart s -> StrictByteString -> IO ()
- verify :: AuthenticationTag -> AuthenticationKey -> StrictByteString -> Bool
- data AuthenticationKey
- newAuthenticationKey :: IO AuthenticationKey
- authenticationKeyFromHexByteString :: StrictByteString -> Either Text AuthenticationKey
- unsafeAuthenticationKeyToBinary :: AuthenticationKey -> StrictByteString
- unsafeAuthenticationKeyToHexByteString :: AuthenticationKey -> StrictByteString
- data AuthenticationTag
- authenticationTagToHexByteString :: AuthenticationTag -> StrictByteString
- authenticationTagToBinary :: AuthenticationTag -> StrictByteString
- authenticationTagFromHexByteString :: StrictByteString -> Either Text AuthenticationTag
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.SHA256 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
-- => TrueOperations
Authenticating a single messsage
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
Authenicating a multi-part message
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
Arguments
| :: forall (a :: Type) (m :: Type -> Type). MonadIO m | |
| => AuthenticationKey | |
| -> (forall s. Multipart s -> m a) | Continuation that gives you access to a |
| -> 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 #
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
data AuthenticationKey Source #
A secret authentication key of size cryptoAuthHMACSHA256Bytes.
Since: 0.0.1.0
Instances
newAuthenticationKey :: IO AuthenticationKey Source #
Generate a new random secret key of size cryptoAuthHMACSHA256KeyBytes.
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
cryptoAuthHMACSHA256Bytes.
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
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
Authentication tag
data AuthenticationTag Source #
A secret authentication key of size cryptoAuthHMACSHA256Bytes.
Since: 0.0.1.0
Instances
authenticationTagToHexByteString :: AuthenticationTag -> StrictByteString Source #
Convert an AuthenticationTag to a hexadecimal-encoded StrictByteString.
Since: 0.0.1.0
authenticationTagToBinary :: AuthenticationTag -> StrictByteString Source #
Convert an AuthenticationTag to a binary StrictByteString.
Since: 0.0.1.0
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
cryptoAuthHMACSHA256Bytes.
Since: 0.0.1.0