poly1305

commit 4cfd6ee134fe7c793813ad8e6d623932ee5ba410
parent 2d662165e27e637f0dcc8ab67391c5f6fa8d7d1a
Author: Jared Tobin <jared@jtobin.io>
Date:   Sun,  9 Mar 2025 17:35:54 +0400

lib: docs

Diffstat:
M
lib/Crypto/MAC/Poly1305.hs
 | 
20
+++++++++++---------

1 file changed, 11 insertions(+), 9 deletions(-)
diff --git a/lib/Crypto/MAC/Poly1305.hs b/lib/Crypto/MAC/Poly1305.hs
@@ -1,3 +1,4 @@
+{-# OPTIONS_HADDOCK prune #-}
 {-# LANGUAGE BangPatterns #-}
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE ViewPatterns #-}
@@ -48,16 +49,18 @@ clamp r = r .&. 0x0ffffffc0ffffffc0ffffffc0fffffff
 -- | Produce a Poly1305 MAC for the provided message, given the provided
 --   key.
 --
---   Per RFC8439, the key must be exactly 256 bits in length. Providing
---   an invalid key will cause the function to throw an ErrorCall
---   exception.
+--   Per RFC8439: the key, which is essentially a /one-time/ key, should
+--   be unique, and MUST be unpredictable for each invocation.
 --
---   >>> mac "don't tell anyone my secret key!" "a message needing authentication"
---   ";]\a\USf\132A\156\b\171-_\162-\201R"
+--   The key must be exactly 256 bits in length. Providing an invalid
+--   key will cause the function to throw an ErrorCall exception.
+--
+--   >>> mac "i'll never use this key again!!!" "a message needing authentication"
+--   "O'\231Z\224\149\148\246\203[}\210\203\b\200\207"
 mac
-  :: BS.ByteString -- ^ key
-  -> BS.ByteString -- ^ message
-  -> BS.ByteString -- ^ message authentication code
+  :: BS.ByteString -- ^ 256-bit one-time key
+  -> BS.ByteString -- ^ arbitrary-length message
+  -> BS.ByteString -- ^ 128-bit message authentication code
 mac key@(BI.PS _ _ kl) msg
     | kl /= 32  = error "ppad-poly1305 (mac): invalid key"
     | otherwise =
@@ -75,4 +78,3 @@ mac key@(BI.PS _ _ kl) msg
   where
     p = 1361129467683753853853498429727072845819 -- (1 << 130) - 5
 
-