{-# OPTIONS_HADDOCK prune #-}
{-# LANGUAGE BangPatterns #-}

-- |
-- Module: Crypto.Cipher.ChaCha
-- Copyright: (c) 2026 Jared Tobin
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
-- ChaCha keystreams with 8, 12, or 20 rounds, using the state layout
-- of [RFC 8439](https://datatracker.ietf.org/doc/html/rfc8439).
--
-- The reduced-round variants are intended for uses such as
-- random number generation; use "Crypto.Cipher.ChaCha20" for
-- encryption.

module Crypto.Cipher.ChaCha (
    -- * Round counts
    Rounds(..)

    -- * Keystream
  , keystream

    -- * Error information
  , Error(..)

    -- internal
  , FeedForward(..)
  , _keystream_into
  , _interleaved_into
  , _interleaved_pure_into
  ) where

import Control.Monad.ST (runST)
import Data.Bits ((.|.), (.<<.), (.>>.))
import Crypto.Cipher.ChaCha20 (Error(..))
import qualified Crypto.Cipher.ChaCha20 as ChaCha20
import qualified Crypto.Cipher.ChaCha20.Native as Native
import qualified Data.ByteString as BS
import qualified Data.ByteString.Internal as BI
import qualified Data.ByteString.Unsafe as BU
import Data.Foldable (for_)
import Data.Word (Word8, Word32, Word64)
import Foreign.ForeignPtr (withForeignPtr)
import Foreign.Marshal.Utils (copyBytes)
import Foreign.Ptr (Ptr, castPtr, plusPtr)
import Foreign.Storable (pokeByteOff)

-- utils ----------------------------------------------------------------------

fi :: (Integral a, Num b) => a -> b
fi :: forall a b. (Integral a, Num b) => a -> b
fi = a -> b
forall a b. (Integral a, Num b) => a -> b
fromIntegral
{-# INLINE fi #-}

-- rounds ---------------------------------------------------------------------

-- | The number of ChaCha rounds.
data Rounds =
    ChaCha8  -- ^ 8 rounds
  | ChaCha12 -- ^ 12 rounds
  | ChaCha20 -- ^ 20 rounds, as specified by RFC 8439
  deriving (Rounds -> Rounds -> Bool
(Rounds -> Rounds -> Bool)
-> (Rounds -> Rounds -> Bool) -> Eq Rounds
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: Rounds -> Rounds -> Bool
== :: Rounds -> Rounds -> Bool
$c/= :: Rounds -> Rounds -> Bool
/= :: Rounds -> Rounds -> Bool
Eq, Int -> Rounds -> ShowS
[Rounds] -> ShowS
Rounds -> String
(Int -> Rounds -> ShowS)
-> (Rounds -> String) -> ([Rounds] -> ShowS) -> Show Rounds
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> Rounds -> ShowS
showsPrec :: Int -> Rounds -> ShowS
$cshow :: Rounds -> String
show :: Rounds -> String
$cshowList :: [Rounds] -> ShowS
showList :: [Rounds] -> ShowS
Show)

-- number of double rounds
drounds :: Rounds -> Int
drounds :: Rounds -> Int
drounds Rounds
r = case Rounds
r of
  Rounds
ChaCha8  -> Int
4
  Rounds
ChaCha12 -> Int
6
  Rounds
ChaCha20 -> Int
10
{-# INLINE drounds #-}

-- keystream ------------------------------------------------------------------

-- | The ChaCha keystream with the given number of rounds, starting
--   at the given block counter.
--
--   The key must be exactly 256 bits, and the nonce exactly 96 bits.
--   The counter must leave room for the requested number of bytes;
--   non-positive numbers of bytes yield the empty string.
--
--   >>> import qualified Data.ByteString as BS
--   >>> import qualified Data.ByteString.Base16 as B16
--   >>> let key = BS.replicate 32 0
--   >>> let non = BS.replicate 12 0
--   >>> fmap B16.encode (keystream ChaCha8 key 0 non 16)
--   Right "3e00ef2f895f40d67f5bb8e81f09a5a1"
keystream
  :: Rounds         -- ^ number of rounds
  -> BS.ByteString  -- ^ 256-bit key
  -> Word32         -- ^ 32-bit counter
  -> BS.ByteString  -- ^ 96-bit nonce
  -> Int            -- ^ number of bytes
  -> Either Error BS.ByteString -- ^ keystream
keystream :: Rounds
-> ByteString
-> Word32
-> ByteString
-> Int
-> Either Error ByteString
keystream Rounds
r key :: ByteString
key@(BI.PS ForeignPtr Word8
kfp Int
koff Int
kl) Word32
counter nonce :: ByteString
nonce@(BI.PS ForeignPtr Word8
nfp Int
noff Int
nl) Int
len
  | Int
kl Int -> Int -> Bool
forall a. Eq a => a -> a -> Bool
/= Int
32      = Error -> Either Error ByteString
forall a b. a -> Either a b
Left Error
InvalidKey
  | Int
nl Int -> Int -> Bool
forall a. Eq a => a -> a -> Bool
/= Int
12      = Error -> Either Error ByteString
forall a b. a -> Either a b
Left Error
InvalidNonce
  | Int
len Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
<= Int
0      = ByteString -> Either Error ByteString
forall a b. b -> Either a b
Right ByteString
BS.empty
  | Int -> Word64
forall a b. (Integral a, Num b) => a -> b
fi Int
len Word64 -> Word64 -> Bool
forall a. Ord a => a -> a -> Bool
> Word64
room = Error -> Either Error ByteString
forall a b. a -> Either a b
Left Error
CounterOverflow
  | Bool
Native.chacha20_native_available =
      ByteString -> Either Error ByteString
forall a b. b -> Either a b
Right (ByteString -> Either Error ByteString)
-> ByteString -> Either Error ByteString
forall a b. (a -> b) -> a -> b
$ Int -> (Ptr Word8 -> IO ()) -> ByteString
BI.unsafeCreate Int
len ((Ptr Word8 -> IO ()) -> ByteString)
-> (Ptr Word8 -> IO ()) -> ByteString
forall a b. (a -> b) -> a -> b
$ \Ptr Word8
dst ->
        ForeignPtr Word8 -> (Ptr Word8 -> IO ()) -> IO ()
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Word8
kfp ((Ptr Word8 -> IO ()) -> IO ()) -> (Ptr Word8 -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Ptr Word8
kp ->
        ForeignPtr Word8 -> (Ptr Word8 -> IO ()) -> IO ()
forall a b. ForeignPtr a -> (Ptr a -> IO b) -> IO b
withForeignPtr ForeignPtr Word8
nfp ((Ptr Word8 -> IO ()) -> IO ()) -> (Ptr Word8 -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Ptr Word8
np ->
          Int
-> Ptr Word8 -> Word32 -> Ptr Word8 -> Ptr Word8 -> Int -> IO ()
Native.keystream_into (Rounds -> Int
drounds Rounds
r) (Ptr Word8
kp Ptr Word8 -> Int -> Ptr Word8
forall a b. Ptr a -> Int -> Ptr b
`plusPtr` Int
koff) Word32
counter
            (Ptr Word8
np Ptr Word8 -> Int -> Ptr Word8
forall a b. Ptr a -> Int -> Ptr b
`plusPtr` Int
noff) Ptr Word8
dst Int
len
  | Bool
otherwise = ByteString -> Either Error ByteString
forall a b. b -> Either a b
Right (ByteString -> Either Error ByteString)
-> ByteString -> Either Error ByteString
forall a b. (a -> b) -> a -> b
$ (forall s. ST s ByteString) -> ByteString
forall a. (forall s. ST s a) -> a
runST ((forall s. ST s ByteString) -> ByteString)
-> (forall s. ST s ByteString) -> ByteString
forall a b. (a -> b) -> a -> b
$
      Int -> Key -> Word32 -> Nonce -> ByteString -> ST s ByteString
forall (m :: * -> *).
PrimMonad m =>
Int -> Key -> Word32 -> Nonce -> ByteString -> m ByteString
ChaCha20._cipher_rounds (Rounds -> Int
drounds Rounds
r)
        (ByteString -> Key
ChaCha20._parse_key ByteString
key) Word32
counter (ByteString -> Nonce
ChaCha20._parse_nonce ByteString
nonce)
        (Int -> Word8 -> ByteString
BS.replicate Int
len Word8
0)
  where
    !room :: Word64
room = (Word64
0x100000000 Word64 -> Word64 -> Word64
forall a. Num a => a -> a -> a
- Word32 -> Word64
forall a b. (Integral a, Num b) => a -> b
fi Word32
counter) Word64 -> Word64 -> Word64
forall a. Num a => a -> a -> a
* Word64
64 :: Word64

-- | Write keystream bytes to the destination pointer, for the key and
--   nonce at the given pointers.
--
--   Unchecked: the key and nonce pointers must address 32 and 12
--   bytes respectively, the destination must have room for the given
--   number of bytes and must not overlap the key or nonce, and the
--   counter must leave room for the bytes.
_keystream_into
  :: Rounds    -- ^ number of rounds
  -> Ptr Word8 -- ^ 256-bit key
  -> Word32    -- ^ 32-bit counter
  -> Ptr Word8 -- ^ 96-bit nonce
  -> Ptr Word8 -- ^ destination
  -> Int       -- ^ number of bytes
  -> IO ()
_keystream_into :: Rounds
-> Ptr Word8 -> Word32 -> Ptr Word8 -> Ptr Word8 -> Int -> IO ()
_keystream_into Rounds
r Ptr Word8
kp Word32
counter Ptr Word8
np Ptr Word8
dst Int
len
  | Bool
Native.chacha20_native_available =
      Int
-> Ptr Word8 -> Word32 -> Ptr Word8 -> Ptr Word8 -> Int -> IO ()
Native.keystream_into (Rounds -> Int
drounds Rounds
r) Ptr Word8
kp Word32
counter Ptr Word8
np Ptr Word8
dst Int
len
  | Bool
otherwise = do
      key <- CStringLen -> IO ByteString
BS.packCStringLen (Ptr Word8 -> Ptr CChar
forall a b. Ptr a -> Ptr b
castPtr Ptr Word8
kp, Int
32)
      non <- BS.packCStringLen (castPtr np, 12)
      let !out = (forall s. ST s ByteString) -> ByteString
forall a. (forall s. ST s a) -> a
runST ((forall s. ST s ByteString) -> ByteString)
-> (forall s. ST s ByteString) -> ByteString
forall a b. (a -> b) -> a -> b
$
            Int -> Key -> Word32 -> Nonce -> ByteString -> ST s ByteString
forall (m :: * -> *).
PrimMonad m =>
Int -> Key -> Word32 -> Nonce -> ByteString -> m ByteString
ChaCha20._cipher_rounds (Rounds -> Int
drounds Rounds
r)
              (ByteString -> Key
ChaCha20._parse_key ByteString
key) Word32
counter
              (ByteString -> Nonce
ChaCha20._parse_nonce ByteString
non) (Int -> Word8 -> ByteString
BS.replicate Int
len Word8
0)
      BU.unsafeUseAsCString out $ \Ptr CChar
src ->
        Ptr Word8 -> Ptr Word8 -> Int -> IO ()
forall a. Ptr a -> Ptr a -> Int -> IO ()
copyBytes Ptr Word8
dst (Ptr CChar -> Ptr Word8
forall a b. Ptr a -> Ptr b
castPtr Ptr CChar
src) Int
len

-- interleaved keystream ------------------------------------------------------

-- | Which words of the input state are added to a block's output.
data FeedForward =
    FeedForwardAll -- ^ all words, as standard
  | FeedForwardKey -- ^ the key words only, omitting the public
                   --   constant, counter, and nonce words, as in
                   --   ChaCha8Rand
  deriving (FeedForward -> FeedForward -> Bool
(FeedForward -> FeedForward -> Bool)
-> (FeedForward -> FeedForward -> Bool) -> Eq FeedForward
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: FeedForward -> FeedForward -> Bool
== :: FeedForward -> FeedForward -> Bool
$c/= :: FeedForward -> FeedForward -> Bool
/= :: FeedForward -> FeedForward -> Bool
Eq, Int -> FeedForward -> ShowS
[FeedForward] -> ShowS
FeedForward -> String
(Int -> FeedForward -> ShowS)
-> (FeedForward -> String)
-> ([FeedForward] -> ShowS)
-> Show FeedForward
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> FeedForward -> ShowS
showsPrec :: Int -> FeedForward -> ShowS
$cshow :: FeedForward -> String
show :: FeedForward -> String
$cshowList :: [FeedForward] -> ShowS
showList :: [FeedForward] -> ShowS
Show)

-- | Write groups of four consecutive keystream blocks to the
--   destination pointer, interleaved word by word: within each
--   256-byte group, word i of block j is at byte offset 16 * i + 4 * j.
--   This is the layout that four-way SIMD produces naturally.
--
--   Unchecked: the key and nonce pointers must address 32 and 12
--   bytes respectively, the destination must have room for 256 bytes
--   per group and must not overlap the key or nonce, and the counter
--   must leave room for four blocks per group.
_interleaved_into
  :: Rounds      -- ^ number of rounds
  -> FeedForward -- ^ final addition of the input state
  -> Ptr Word8   -- ^ 256-bit key
  -> Word32      -- ^ 32-bit counter
  -> Ptr Word8   -- ^ 96-bit nonce
  -> Ptr Word8   -- ^ destination
  -> Int         -- ^ number of four-block groups
  -> IO ()
_interleaved_into :: Rounds
-> FeedForward
-> Ptr Word8
-> Word32
-> Ptr Word8
-> Ptr Word8
-> Int
-> IO ()
_interleaved_into Rounds
r FeedForward
ff Ptr Word8
kp Word32
counter Ptr Word8
np Ptr Word8
dst Int
groups
  | Bool
Native.chacha20_native_available =
      Int
-> Bool
-> Ptr Word8
-> Word32
-> Ptr Word8
-> Ptr Word8
-> Int
-> IO ()
Native.interleaved_into (Rounds -> Int
drounds Rounds
r) (FeedForward
ff FeedForward -> FeedForward -> Bool
forall a. Eq a => a -> a -> Bool
== FeedForward
FeedForwardKey) Ptr Word8
kp
        Word32
counter Ptr Word8
np Ptr Word8
dst Int
groups
  | Bool
otherwise = Rounds
-> FeedForward
-> Ptr Word8
-> Word32
-> Ptr Word8
-> Ptr Word8
-> Int
-> IO ()
_interleaved_pure_into Rounds
r FeedForward
ff Ptr Word8
kp Word32
counter Ptr Word8
np Ptr Word8
dst Int
groups

-- | A pure Haskell '_interleaved_into', with the same preconditions.
_interleaved_pure_into
  :: Rounds
  -> FeedForward
  -> Ptr Word8
  -> Word32
  -> Ptr Word8
  -> Ptr Word8
  -> Int
  -> IO ()
_interleaved_pure_into :: Rounds
-> FeedForward
-> Ptr Word8
-> Word32
-> Ptr Word8
-> Ptr Word8
-> Int
-> IO ()
_interleaved_pure_into Rounds
r FeedForward
ff Ptr Word8
kp Word32
counter Ptr Word8
np Ptr Word8
dst Int
groups = do
  key <- CStringLen -> IO ByteString
BS.packCStringLen (Ptr Word8 -> Ptr CChar
forall a b. Ptr a -> Ptr b
castPtr Ptr Word8
kp, Int
32)
  non <- BS.packCStringLen (castPtr np, 12)
  let !ks = (forall s. ST s ByteString) -> ByteString
forall a. (forall s. ST s a) -> a
runST ((forall s. ST s ByteString) -> ByteString)
-> (forall s. ST s ByteString) -> ByteString
forall a b. (a -> b) -> a -> b
$
        Int -> Key -> Word32 -> Nonce -> ByteString -> ST s ByteString
forall (m :: * -> *).
PrimMonad m =>
Int -> Key -> Word32 -> Nonce -> ByteString -> m ByteString
ChaCha20._cipher_rounds (Rounds -> Int
drounds Rounds
r)
          (ByteString -> Key
ChaCha20._parse_key ByteString
key) Word32
counter (ByteString -> Nonce
ChaCha20._parse_nonce ByteString
non)
          (Int -> Word8 -> ByteString
BS.replicate (Int
256 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
groups) Word8
0)
      -- the input word that the final addition omits
      omit Int
i a
blk = case FeedForward
ff of
        FeedForward
FeedForwardAll -> Word32
0
        FeedForward
FeedForwardKey
          | Int
i Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
< Int
4     -> Int -> Word32
constant Int
i
          | Int
i Int -> Int -> Bool
forall a. Eq a => a -> a -> Bool
== Int
12   -> Word32
counter Word32 -> Word32 -> Word32
forall a. Num a => a -> a -> a
+ a -> Word32
forall a b. (Integral a, Num b) => a -> b
fi a
blk
          | Int
i Int -> Int -> Bool
forall a. Ord a => a -> a -> Bool
> Int
12    -> ByteString -> Int -> Word32
le32_at ByteString
non (Int
4 Int -> Int -> Int
forall a. Num a => a -> a -> a
* (Int
i Int -> Int -> Int
forall a. Num a => a -> a -> a
- Int
13))
          | Bool
otherwise -> Word32
0
  for_ [0 .. groups - 1] $ \Int
g ->
    [Int] -> (Int -> IO ()) -> IO ()
forall (t :: * -> *) (f :: * -> *) a b.
(Foldable t, Applicative f) =>
t a -> (a -> f b) -> f ()
for_ [Int
0 .. Int
15] ((Int -> IO ()) -> IO ()) -> (Int -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Int
i ->
      [Int] -> (Int -> IO ()) -> IO ()
forall (t :: * -> *) (f :: * -> *) a b.
(Foldable t, Applicative f) =>
t a -> (a -> f b) -> f ()
for_ [Int
0 .. Int
3] ((Int -> IO ()) -> IO ()) -> (Int -> IO ()) -> IO ()
forall a b. (a -> b) -> a -> b
$ \Int
j -> do
        let !blk :: Int
blk = Int
4 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
g Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
j
            !v :: Word32
v   = ByteString -> Int -> Word32
le32_at ByteString
ks (Int
64 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
blk Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
4 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
i) Word32 -> Word32 -> Word32
forall a. Num a => a -> a -> a
- Int -> Int -> Word32
forall {a}. Integral a => Int -> a -> Word32
omit Int
i Int
blk
        Ptr Word8 -> Word32 -> IO ()
poke_le32 (Ptr Word8
dst Ptr Word8 -> Int -> Ptr Word8
forall a b. Ptr a -> Int -> Ptr b
`plusPtr` (Int
256 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
g Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
16 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
i Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
4 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int
j)) Word32
v
  where
    constant :: Int -> Word32
    constant :: Int -> Word32
constant Int
i = case Int
i of
      Int
0 -> Word32
0x61707865
      Int
1 -> Word32
0x3320646e
      Int
2 -> Word32
0x79622d32
      Int
_ -> Word32
0x6b206574

-- little-endian word at the given (in-bounds) offset
le32_at :: BS.ByteString -> Int -> Word32
le32_at :: ByteString -> Int -> Word32
le32_at ByteString
bs Int
o =
      Word8 -> Word32
forall a b. (Integral a, Num b) => a -> b
fi (ByteString -> Int -> Word8
BU.unsafeIndex ByteString
bs Int
o)
  Word32 -> Word32 -> Word32
forall a. Bits a => a -> a -> a
.|. (Word8 -> Word32
forall a b. (Integral a, Num b) => a -> b
fi (ByteString -> Int -> Word8
BU.unsafeIndex ByteString
bs (Int
o Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
1)) Word32 -> Int -> Word32
forall a. Bits a => a -> Int -> a
.<<. Int
8)
  Word32 -> Word32 -> Word32
forall a. Bits a => a -> a -> a
.|. (Word8 -> Word32
forall a b. (Integral a, Num b) => a -> b
fi (ByteString -> Int -> Word8
BU.unsafeIndex ByteString
bs (Int
o Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
2)) Word32 -> Int -> Word32
forall a. Bits a => a -> Int -> a
.<<. Int
16)
  Word32 -> Word32 -> Word32
forall a. Bits a => a -> a -> a
.|. (Word8 -> Word32
forall a b. (Integral a, Num b) => a -> b
fi (ByteString -> Int -> Word8
BU.unsafeIndex ByteString
bs (Int
o Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
3)) Word32 -> Int -> Word32
forall a. Bits a => a -> Int -> a
.<<. Int
24)
{-# INLINE le32_at #-}

poke_le32 :: Ptr Word8 -> Word32 -> IO ()
poke_le32 :: Ptr Word8 -> Word32 -> IO ()
poke_le32 Ptr Word8
p Word32
w = do
  Ptr Word8 -> Int -> Word8 -> IO ()
forall b. Ptr b -> Int -> Word8 -> IO ()
forall a b. Storable a => Ptr b -> Int -> a -> IO ()
pokeByteOff Ptr Word8
p Int
0 (Word32 -> Word8
forall a b. (Integral a, Num b) => a -> b
fi Word32
w :: Word8)
  Ptr Word8 -> Int -> Word8 -> IO ()
forall b. Ptr b -> Int -> Word8 -> IO ()
forall a b. Storable a => Ptr b -> Int -> a -> IO ()
pokeByteOff Ptr Word8
p Int
1 (Word32 -> Word8
forall a b. (Integral a, Num b) => a -> b
fi (Word32
w Word32 -> Int -> Word32
forall a. Bits a => a -> Int -> a
.>>. Int
8) :: Word8)
  Ptr Word8 -> Int -> Word8 -> IO ()
forall b. Ptr b -> Int -> Word8 -> IO ()
forall a b. Storable a => Ptr b -> Int -> a -> IO ()
pokeByteOff Ptr Word8
p Int
2 (Word32 -> Word8
forall a b. (Integral a, Num b) => a -> b
fi (Word32
w Word32 -> Int -> Word32
forall a. Bits a => a -> Int -> a
.>>. Int
16) :: Word8)
  Ptr Word8 -> Int -> Word8 -> IO ()
forall b. Ptr b -> Int -> Word8 -> IO ()
forall a b. Storable a => Ptr b -> Int -> a -> IO ()
pokeByteOff Ptr Word8
p Int
3 (Word32 -> Word8
forall a b. (Integral a, Num b) => a -> b
fi (Word32
w Word32 -> Int -> Word32
forall a. Bits a => a -> Int -> a
.>>. Int
24) :: Word8)
{-# INLINE poke_le32 #-}