crypton-2.3.0: Crypto/Random/SysDRG.hs
{-# LANGUAGE ForeignFunctionInterface #-}
-- |
-- Module : Crypto.Random.SysDRG
-- License : BSD-style
-- Maintainer : Kazu Yamamoto <kazu@iij.ad.jp>
-- Stability : experimental
-- Portability : Unix, Windows
--
-- The generator behind the 'Crypto.Random.MonadRandom' instance for 'IO'.
--
-- By default every draw takes a fresh key from the system and keeps
-- nothing ('SystemRandomPerDraw'). What follows describes the faster
-- 'SystemRandomPerThread' mode.
--
-- A ChaCha20 generator per operating system thread, seeded straight from
-- the system entropy pool.
-- The state and the reseeding live in
-- @cbits\/crypton_sysdrg.c@, because a @forkIO@ thread is not an operating
-- system thread -- it moves between capabilities -- so state held against
-- one would be shared by threads running at the same time.
--
-- == What it is, and what it is not
--
-- It is not a DRBG of NIST SP 800-90A. That standard names three --
-- @Hash_DRBG@, @HMAC_DRBG@ and @CTR_DRBG@ -- and none of them is built on a
-- stream cipher. The name here is the older and looser sense of the word.
--
-- What it is is the shape @arc4random@ on OpenBSD and @get_random_bytes@ in
-- the Linux kernel both have, and the one asked for in
-- <https://github.com/kazu-yamamoto/crypton/issues/298>. That shape is
-- common; it is not specified anywhere, so the parts a standard would have
-- fixed were chosen here instead:
--
-- * ChaCha20, rather than AES in counter mode.
-- * SHA-512 over the system's bytes, rather than a derivation function a
-- standard would have named.
-- * A mebibyte per thread as the point at which to reseed. That number is
-- a choice, not a result.
--
-- The pieces underneath are specified: ChaCha20 is RFC 8439, SHA-512 is
-- FIPS 180-4. The way they are put together is not.
--
-- == What a compromised state gives away
--
-- Each draw ends by taking the next forty bytes of keystream as the key and
-- nonce and dropping the ones that made the output, so a state read after a
-- draw is not the state that produced it. ChaCha20 does not run backwards
-- and the key that would be needed is gone, which is backtracking
-- resistance in the terms of SP 800-90A. Without it, a key stands until
-- the next reseed and anyone holding the state can wind the counter back
-- over everything issued since -- a mebibyte of output that was meant to be
-- secret. It is what @arc4random@ does, and for the same reason.
--
-- Prediction resistance is what the reseeding gives. A reseed draws from
-- the system again, so a state that has been read does not determine what
-- comes after one.
module Crypto.Random.SysDRG (
sysDRGBytes,
sysDRGReseed,
SystemRandomMode (..),
setSystemRandomMode,
getSystemRandomMode,
) where
import Data.Word (Word32, Word8)
import Foreign.C.Types (CInt (..))
import Foreign.Ptr (Ptr)
import Crypto.Internal.ByteArray (ByteArray)
import qualified Crypto.Internal.ByteArray as B
-- Safe, not unsafe: seeding can reach a getrandom(2) that blocks until the
-- kernel pool is ready, and an unsafe call that blocks holds the capability
-- it runs on.
foreign import ccall safe "crypton_sysdrg_bytes"
c_sysdrg_bytes :: Ptr Word8 -> CInt -> IO CInt
-- | Draw bytes, or 'Nothing' if the generator cannot be seeded.
--
-- It cannot be seeded where the system has no @getrandom(2)@ or
-- @getentropy(3)@; the caller falls back to
-- 'Crypto.Random.Entropy.getEntropy' there, which is the path this system
-- had before the generator existed.
sysDRGBytes :: ByteArray byteArray => Int -> IO (Maybe byteArray)
sysDRGBytes n = do
(got, out) <- B.allocRet n $ \ptr ->
fromIntegral `fmap` c_sysdrg_bytes ptr (fromIntegral n)
return $ if got == n then Just out else Nothing
-- Unsafe: it only bumps an atomic counter.
foreign import ccall unsafe "crypton_sysdrg_reseed"
c_sysdrg_reseed :: IO ()
-- | Make every generator reseed before it answers again. See
-- 'Crypto.Random.reseedSystem'.
sysDRGReseed :: IO ()
sysDRGReseed = c_sysdrg_reseed
-- | Where the bytes behind 'Crypto.Random.MonadRandom' for 'IO' come from.
data SystemRandomMode
= -- | A fresh key from the system for every draw, expanded with ChaCha20
-- and dropped. Nothing is kept between draws, so copies of a process
-- restored from one saved image -- a virtual machine snapshot, a CRIU
-- checkpoint -- do not repeat each other's bytes. The default.
SystemRandomPerDraw
| -- | A ChaCha20 generator per operating system thread, reseeded from the
-- system after a mebibyte, after a fork, after
-- 'Crypto.Random.reseedSystem', and, unless the interval is 0, once
-- this many milliseconds of running time have passed since its last
-- seed (the default is 10) or when realtime has moved a second or
-- more against the monotonic clock, as a CRIU restore does. With 0
-- the clocks are not read at all. Several times faster
-- for small draws. A restored virtual machine snapshot moves neither
-- clock, so its copies repeat each other until one of these happens.
SystemRandomPerThread Int
deriving (Show, Eq)
foreign import ccall unsafe "crypton_sysdrg_set_mode"
c_sysdrg_set_mode :: CInt -> Word32 -> IO ()
foreign import ccall unsafe "crypton_sysdrg_get_mode"
c_sysdrg_get_mode :: IO CInt
foreign import ccall unsafe "crypton_sysdrg_get_interval"
c_sysdrg_get_interval :: IO Word32
-- | Choose the mode for the whole process. An interval below 0 or above
-- 2^32 - 1 milliseconds is an error.
setSystemRandomMode :: SystemRandomMode -> IO ()
setSystemRandomMode SystemRandomPerDraw = do
t <- c_sysdrg_get_interval
c_sysdrg_set_mode 0 t
setSystemRandomMode (SystemRandomPerThread t)
| t < 0 || toInteger t > toInteger (maxBound :: Word32) =
error "setSystemRandomMode: reseed interval out of range"
| otherwise = c_sysdrg_set_mode 1 (fromIntegral t)
-- | The mode in force.
getSystemRandomMode :: IO SystemRandomMode
getSystemRandomMode = do
m <- c_sysdrg_get_mode
if m == 1
then SystemRandomPerThread . fromIntegral <$> c_sysdrg_get_interval
else return SystemRandomPerDraw