-- | 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. module Crypto.Tutorial ( -- * API design -- $api_design -- * Hash algorithms -- $hash_algorithms -- * Authenticated encryption -- $authenticated_encryption -- * Comparing secrets -- $comparing_secrets -- * Password storage -- $password_storage -- * Key derivation -- $key_derivation -- * Digital signatures -- $digital_signatures -- * Combining primitives -- $combining_primitives ) where -- $api_design -- -- APIs in crypton are often based on type classes from package -- <https://hackage.haskell.org/package/ram ram>, notably -- 'Data.ByteArray.ByteArrayAccess' and 'Data.ByteArray.ByteArray'. -- Module "Data.ByteArray" provides many primitives that are useful to -- work with crypton types. For example function 'Data.ByteArray.convert' -- can transform one 'Data.ByteArray.ByteArrayAccess' concrete type like -- 'Crypto.Hash.Digest' to a 'Data.ByteString.ByteString'. -- -- Algorithms and functions needing random bytes are based on type class -- 'Crypto.Random.Types.MonadRandom'. Implementation 'IO' uses a system source -- of entropy. It is also possible to use a 'Crypto.Random.Types.DRG' with -- 'Crypto.Random.Types.MonadPseudoRandom' -- -- Error conditions are returned with data type 'Crypto.Error.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 -- 'Data.ByteArray.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 'Crypto.Cipher.Types.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: 'Crypto.MAC.HMAC.HMAC', -- 'Crypto.MAC.CMAC.CMAC', 'Crypto.MAC.Poly1305.Auth' and -- 'Crypto.Cipher.Types.AuthTag' have an 'Eq' that looks at every byte -- whatever it finds. What needs care is a tag that arrives as bytes, and -- 'Data.ByteArray.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