crypton
Safe HaskellSafe-Inferred
LanguageHaskell2010

Crypto.Tutorial

Description

Examples of how to use crypton.

Every code block here is extracted and compiled against this version of the library by tests/tutorial/run.sh, so what is written below builds.

Synopsis

    API design

    APIs in crypton are often based on type classes from package ram, notably ByteArrayAccess and ByteArray. Module Data.ByteArray provides many primitives that are useful to work with crypton types. For example function convert can transform one ByteArrayAccess concrete type like Digest to a ByteString.

    Algorithms and functions needing random bytes are based on type class MonadRandom. Implementation IO uses a system source of entropy. It is also possible to use a DRG with MonadPseudoRandom

    Error conditions are returned with data type CryptoFailable. Functions in module Crypto.Error can convert those values to runtime exceptions, Maybe or Either values.

    Types that hold a secret do not print it. A private key's Show renders whatever is public and <secret> or <scrubbed-bytes> for the rest, because Show is what print, error, an exception and a failing test all reach for, and a key arriving in a log that way is an accident nobody asked for. Crypto.Debug is how one is printed when printing it is what was meant. Several of those types keep their bytes in ScrubbedBytes, which is wiped when it is collected.

    Hash algorithms

    Hashing a complete message:

    import Crypto.Hash
    
    import Data.ByteString (ByteString)
    
    exampleHashWith :: ByteString -> IO ()
    exampleHashWith msg = do
        putStrLn $ "  sha1(" ++ show msg ++ ") = " ++ show (hashWith SHA1   msg)
        putStrLn $ "sha256(" ++ show msg ++ ") = " ++ show (hashWith SHA256 msg)

    Hashing incrementally, with intermediate context allocations:

    {-# LANGUAGE OverloadedStrings #-}
    
    import Crypto.Hash
    
    import Data.ByteString (ByteString)
    
    exampleIncrWithAllocs :: IO ()
    exampleIncrWithAllocs = do
        let ctx0 = hashInitWith SHA3_512
            ctx1 = hashUpdate ctx0 ("The "   :: ByteString)
            ctx2 = hashUpdate ctx1 ("quick " :: ByteString)
            ctx3 = hashUpdate ctx2 ("brown " :: ByteString)
            ctx4 = hashUpdate ctx3 ("fox "   :: ByteString)
            ctx5 = hashUpdate ctx4 ("jumps " :: ByteString)
            ctx6 = hashUpdate ctx5 ("over "  :: ByteString)
            ctx7 = hashUpdate ctx6 ("the "   :: ByteString)
            ctx8 = hashUpdate ctx7 ("lazy "  :: ByteString)
            ctx9 = hashUpdate ctx8 ("dog"    :: ByteString)
        print (hashFinalize ctx9)

    Hashing incrementally, updating context in place:

    {-# LANGUAGE OverloadedStrings #-}
    
    import Crypto.Hash.Algorithms
    import Crypto.Hash.IO
    
    import Data.ByteString (ByteString)
    
    exampleIncrInPlace :: IO ()
    exampleIncrInPlace = do
        ctx <- hashMutableInitWith SHA3_512
        hashMutableUpdate ctx ("The "   :: ByteString)
        hashMutableUpdate ctx ("quick " :: ByteString)
        hashMutableUpdate ctx ("brown " :: ByteString)
        hashMutableUpdate ctx ("fox "   :: ByteString)
        hashMutableUpdate ctx ("jumps " :: ByteString)
        hashMutableUpdate ctx ("over "  :: ByteString)
        hashMutableUpdate ctx ("the "   :: ByteString)
        hashMutableUpdate ctx ("lazy "  :: ByteString)
        hashMutableUpdate ctx ("dog"    :: ByteString)
        hashMutableFinalize ctx >>= print

    Authenticated encryption

    Encrypting hides a message; it does not stop anyone changing it. Under a counter or stream mode, flipping a bit of the ciphertext flips the same bit of the plaintext, and the receiver has no way to tell. An AEAD mode binds the message, and anything else named as associated data, to a short authentication tag, and decrypting something that does not match that tag returns nothing at all.

    That is the mode to use. The unauthenticated ones are in this library for protocols that authenticate separately, not as a starting point.

    {-# LANGUAGE OverloadedStrings #-}
    
    import           Crypto.Cipher.AES (AES256)
    import           Crypto.Cipher.Types
                         ( AEADMode (AEAD_GCM)
                         , AuthTag
                         , BlockCipher (aeadInit)
                         , Cipher (cipherInit, cipherKeySize)
                         , KeySizeSpecifier (..)
                         , aeadSimpleDecrypt
                         , aeadSimpleEncrypt
                         )
    import           Crypto.Error (CryptoError, eitherCryptoError)
    import qualified Crypto.Random.Types as CRT
    
    import           Data.ByteArray (ByteArray, ByteArrayAccess, ScrubbedBytes)
    import           Data.ByteString (ByteString)
    
    -- | A key of the length the cipher asks for, rather than a length
    -- written out here.  ScrubbedBytes rather than ByteString, so that it
    -- is wiped when it is collected and does not print.
    genSecretKey :: (Cipher c, CRT.MonadRandom m) => c -> m ScrubbedBytes
    genSecretKey c = CRT.getRandomBytes (longest (cipherKeySize c))
      where
        longest (KeySizeFixed n)   = n
        longest (KeySizeRange _ n) = n
        longest (KeySizeEnum ns)   = maximum ns
    
    -- | A fresh nonce for every message.  GCM must never see one twice
    -- under the same key: a repeat does not just expose those two messages,
    -- it hands over the key that authenticates all of them.  Twelve random
    -- bytes, sent along with the ciphertext.
    genNonce :: CRT.MonadRandom m => m ByteString
    genNonce = CRT.getRandomBytes 12
    
    -- | Encrypt and authenticate.  The associated data is authenticated but
    -- not encrypted: it is for what the receiver can already see and must
    -- not have had altered, such as a header or an address.
    encrypt
        :: (ByteArray key, ByteArrayAccess nonce, ByteArrayAccess aad, ByteArray ba)
        => key -> nonce -> aad -> ba -> Either CryptoError (AuthTag, ba)
    encrypt key nonce aad plaintext = do
        cipher <- eitherCryptoError (cipherInit key) :: Either CryptoError AES256
        aead <- eitherCryptoError (aeadInit AEAD_GCM cipher nonce)
        return (aeadSimpleEncrypt aead aad plaintext 16)
    
    -- | And back, with two different failures.  Left is this code used
    -- wrongly -- a key of the wrong length, a mode the cipher has not got.
    -- Nothing is a message that is not the one that was sent; it carries no
    -- plaintext and says nothing about which byte was wrong, both of which
    -- are the point.
    decrypt
        :: (ByteArray key, ByteArrayAccess nonce, ByteArrayAccess aad, ByteArray ba)
        => key -> nonce -> aad -> AuthTag -> ba -> Either CryptoError (Maybe ba)
    decrypt key nonce aad tag ciphertext = do
        cipher <- eitherCryptoError (cipherInit key) :: Either CryptoError AES256
        aead <- eitherCryptoError (aeadInit AEAD_GCM cipher nonce)
        return (aeadSimpleDecrypt aead aad ciphertext tag)
    
    exampleAES256GCM :: ByteString -> IO ()
    exampleAES256GCM msg = do
        key <- genSecretKey (undefined :: AES256)
        nonce <- genNonce
        let aad = "to: alice" :: ByteString
        case encrypt key nonce aad msg of
            Left err -> error (show err)
            Right (tag, ciphertext) -> do
                putStrLn $ "ciphertext: " ++ show ciphertext
                putStrLn $ "       tag: " ++ show tag
                putStrLn $ " recovered: "
                    ++ show (decrypt key nonce aad tag ciphertext)
                -- The same bytes and the same tag, with one thing changed
                -- that was never encrypted: Right Nothing.
                putStrLn $ "redirected: "
                    ++ show (decrypt key nonce ("to: eve" :: ByteString) tag ciphertext)

    The two functions above work for any cipher that has an AEAD mode; what changes is the mode given to aeadInit. Crypto.Cipher.ChaChaPoly1305 is the one to prefer on a machine with no AES instructions, and Crypto.Cipher.AESGCMSIV is the one that survives a repeated nonce, at the price of needing the whole message before it can begin.

    Comparing secrets

    Comparing two byte strings with == stops at the first byte that differs, so how long it takes says where that byte was. Against an authentication tag that is the whole secret: someone who can send a guess and time the answer finds the first byte in a few hundred tries, then the second, and has a tag that was supposed to cost 2^128 in a few thousand.

    crypton's own authentication types already compare in constant time, so for those there is nothing to do: HMAC, CMAC, Auth and AuthTag have an Eq that looks at every byte whatever it finds. What needs care is a tag that arrives as bytes, and constEq is the comparison for it.

    {-# LANGUAGE OverloadedStrings #-}
    
    import           Crypto.Hash.Algorithms (SHA256)
    import           Crypto.MAC.HMAC (HMAC, hmac)
    
    import qualified Data.ByteArray as BA
    import           Data.ByteString (ByteString)
    
    -- | The tag came off the wire as bytes, so it is compared as bytes.
    authentic :: ByteString -> ByteString -> ByteString -> Bool
    authentic key message tag =
        BA.constEq tag (hmac key message :: HMAC SHA256)
    
    -- | Once it has been parsed into the library's own type, (==) is
    -- already the constant-time comparison.
    authentic' :: ByteString -> ByteString -> HMAC SHA256 -> Bool
    authentic' key message tag = tag == hmac key message

    Password storage

    A password is not a key. It is short and it is guessable, and whoever takes the database can try every likely one without being watched. What answers that is a function that is deliberately expensive to compute, and crypton has four: Crypto.KDF.BCrypt, Crypto.KDF.Scrypt, Crypto.KDF.Argon2 and Crypto.KDF.PBKDF2. A plain hash is not one of them, however many times it is applied by hand.

    bcrypt leaves the least to get wrong, because the record it returns carries the salt and the cost inside it:

    import Crypto.KDF.BCrypt (hashPassword, validatePassword)
    
    import Data.ByteString (ByteString)
    
    -- | What goes in the database.  The salt is drawn inside and ends up in
    -- the result, so two accounts with the same password do not look alike.
    register :: ByteString -> IO ByteString
    register password = hashPassword 12 password
    
    -- | And what is checked against it.  The cost comes out of the stored
    -- record, so raising it for new accounts leaves the old ones working.
    login :: ByteString -> ByteString -> Bool
    login password stored = validatePassword password stored

    Argon2 is the stronger choice and the one to pick for something new: it asks for memory as well as time, which is what takes the advantage away from the hardware that bcrypt's small working set leaves room for. Nothing is encoded for the caller, though -- the salt and the options are theirs to store, and without all three the hash cannot be recomputed when the user comes back.

    import           Crypto.Error (CryptoFailable)
    import qualified Crypto.KDF.Argon2 as Argon2
    import qualified Crypto.Random.Types as CRT
    
    import           Data.ByteString (ByteString)
    
    -- | Argon2id, which is the variant to prefer: it resists both a machine
    -- built to guess and a process watching the cache.
    options :: Argon2.Options
    options = Argon2.defaultOptions{Argon2.variant = Argon2.Argon2id}
    
    newSalt :: CRT.MonadRandom m => m ByteString
    newSalt = CRT.getRandomBytes 16
    
    derive :: ByteString -> ByteString -> CryptoFailable ByteString
    derive salt password = Argon2.hash options password salt 32

    Key derivation

    HKDF turns one secret into as many keys as a protocol needs. It is for material that is already unguessable -- what comes out of a Diffie-Hellman, or a key already agreed -- and it is deliberately cheap, which is exactly what makes it the wrong thing for a password. Those go to the section above.

    The info string is what keeps the outputs independent: the same secret with a different info gives an unrelated key, so each use of a secret names itself there.

    {-# LANGUAGE OverloadedStrings #-}
    
    import           Crypto.Hash.Algorithms (SHA256)
    import qualified Crypto.KDF.HKDF as HKDF
    
    import           Data.ByteArray (ScrubbedBytes)
    import           Data.ByteString (ByteString)
    
    -- | One shared secret in, two unrelated keys out.
    directionKeys :: ByteString -> ByteString -> (ScrubbedBytes, ScrubbedBytes)
    directionKeys salt shared = (keyFor "client write", keyFor "server write")
      where
        prk = HKDF.extract salt shared :: HKDF.PRK SHA256
        keyFor info = HKDF.expand prk (info :: ByteString) 32

    Digital signatures

    Ed25519 is the one to reach for. The keys are thirty-two bytes, there is nothing to choose and nothing to encode, and signing needs no randomness, so it cannot be ruined by a bad source of it. Crypto.PubKey.Ed448 is the same shape at a larger size, Crypto.PubKey.ECDSA and Crypto.PubKey.RSA.PSS are there for protocols that ask for them, and Crypto.PubKey.MLDSA is the post-quantum one.

    {-# LANGUAGE OverloadedStrings #-}
    
    import           Crypto.Error (throwCryptoError)
    import qualified Crypto.PubKey.Ed25519 as Ed25519
    
    import qualified Data.ByteArray as BA
    import           Data.ByteString (ByteString)
    
    exampleEd25519 :: ByteString -> IO ()
    exampleEd25519 msg = do
        sk <- Ed25519.generateSecretKey
        let pk = Ed25519.toPublic sk
            sig = Ed25519.sign sk pk msg
        print (Ed25519.verify pk msg sig)
        -- The same signature against a message one byte longer: False.
        print (Ed25519.verify pk (msg <> "!") sig)
    
    -- | A secret key on its way to storage.  Printing one does not reveal
    -- it -- see the first section -- so this is the way out.
    store :: Ed25519.SecretKey -> ByteString
    store = BA.convert
    
    -- | And the way back in, which is checked, because the bytes read from
    -- a file may be anything at all.
    load :: ByteString -> Ed25519.SecretKey
    load = throwCryptoError . Ed25519.secretKey

    Combining primitives

    This example shows how to use Curve25519, XSalsa and Poly1305 primitives to emulate NaCl's crypto_box construct.

    It is here to show how the pieces fit together, not as something to deploy. An authenticated encryption scheme assembled by hand is the kind of code that is wrong in ways no test notices; for actual use, Crypto.Cipher.ChaChaPoly1305 does this job with the mistakes already made.

    import qualified Data.ByteArray as BA
    import           Data.ByteString (ByteString)
    import qualified Data.ByteString as B
    
    import           Crypto.Error (throwCryptoError)
    import qualified Crypto.Cipher.XSalsa as XSalsa
    import qualified Crypto.MAC.Poly1305 as Poly1305
    import qualified Crypto.PubKey.Curve25519 as X25519
    
    -- | Build a @crypto_box@ packet encrypting the specified content with a
    -- 192-bit nonce, receiver public key and sender private key.
    crypto_box
        :: ByteString -> ByteString -> X25519.PublicKey -> X25519.SecretKey
        -> ByteString
    crypto_box content nonce pk sk = BA.convert tag `B.append` c
      where
        zero         = B.replicate 16 0
        shared       = X25519.dh pk sk
        (iv0, iv1)   = B.splitAt 8 nonce
        state0       = XSalsa.initialize 20 shared (zero `B.append` iv0)
        state1       = XSalsa.derive state0 iv1
        (rs, state2) = XSalsa.generate state1 32
        (c, _)       = XSalsa.combine state2 content
        macKey       = throwCryptoError (Poly1305.key (rs :: ByteString))
        tag          = Poly1305.auth macKey c
    
    -- | Try to open a @crypto_box@ packet and recover the content using the
    -- 192-bit nonce, sender public key and receiver private key.
    crypto_box_open
        :: ByteString -> ByteString -> X25519.PublicKey -> X25519.SecretKey
        -> Maybe ByteString
    crypto_box_open packet nonce pk sk
        | B.length packet < 16 = Nothing
        | BA.constEq tag' tag  = Just content
        | otherwise            = Nothing
      where
        (tag', c)    = B.splitAt 16 packet
        zero         = B.replicate 16 0
        shared       = X25519.dh pk sk
        (iv0, iv1)   = B.splitAt 8 nonce
        state0       = XSalsa.initialize 20 shared (zero `B.append` iv0)
        state1       = XSalsa.derive state0 iv1
        (rs, state2) = XSalsa.generate state1 32
        (content, _) = XSalsa.combine state2 c
        macKey       = throwCryptoError (Poly1305.key (rs :: ByteString))
        tag          = Poly1305.auth macKey c