raaz 0.3.4 → 0.3.5

raw patch · 11 files changed

+85/−72 lines, 11 files

Files

• CHANGELOG.md +12/−0
• api/aead/Auth/Implementation.hsig +5/−2
• api/aead/Cipher/Implementation.hsig +4/−0
• api/auth/Implementation.hsig +4/−2
• api/digest/Implementation.hsig +4/−2
• raaz.cabal +1/−1
• raaz/Raaz/Auth.hs +5/−0
• raaz/Raaz/AuthEncrypt.hs +23/−53
• raaz/Raaz/AuthEncrypt/Unsafe.hs +17/−11
• raaz/Raaz/Digest.hs +6/−0
• raaz/Raaz/V1/AuthEncrypt/Unsafe.hs +4/−1

@@ -1,5 +1,14 @@ # Change log for [raaz]. +## [0.3.5] - Oct 10, 2021++Make things more friendly for serialisation.++- Enforce Encodable instance on Digest, AuthTag, and Nounce.++- Exppose unsafeToNounce for conversion from AEAD token to Nounce.++ ## [0.3.4] - Oct 7, 2021  This is yet another release trying to work out the cabal-install@@ -176,4 +185,7 @@ [0.3.0]: <http://github.com/raaz-crypto/raaz/releases/tag/v0.3.0> [0.3.1]: <http://github.com/raaz-crypto/raaz/releases/tag/v0.3.1> [0.3.2]: <http://github.com/raaz-crypto/raaz/releases/tag/v0.3.2>+[0.3.3]: <http://github.com/raaz-crypto/raaz/releases/tag/v0.3.3>+[0.3.4]: <http://github.com/raaz-crypto/raaz/releases/tag/v0.3.4>+[0.3.5]: <http://github.com/raaz-crypto/raaz/releases/tag/v0.3.5> [raaz]:  <http://github.com/raaz-crypto/raaz/>

@@ -13,8 +13,11 @@ data Prim data Internals -instance Eq Prim-instance Equality Prim+instance Eq Prim            -- We need ability to compare+instance Equality Prim      -- Timing safe comparison when part of a+                            -- compound type+instance Encodable Prim    -- To serialise authentication tag.+ instance Memory Internals instance WriteAccessible Internals instance Extractable Internals Prim

@@ -14,6 +14,9 @@ -- -- 3. Initialise the BlockCount --+-- In addition to serialise the corresponding locked data we would+-- need Encodable instance for the nounce.+ signature Cipher.Implementation where  import           Raaz.Core@@ -26,6 +29,7 @@ instance Memory Internals  instance Initialisable Internals (Key Prim)+instance Encodable (Nounce Prim)  -- | Write access to key is provided. instance WriteAccessible Internals

@@ -10,9 +10,10 @@ -- -- 1. The `Prim` type captures the message authentication code and --    hence should be instances of `Eq`, so that we can compare---    messages by checking the digest, and `Equality`, so that the+--    messages by checking the digest, `Equality`, so that the --    equality comparison can be made timing safe when part of a---    compound data.+--    compound data, and `Encodeable` so that we can serialise the+--    authentication code to a byte string. -- -- 2. To start the process of computing the message authentication, --    the `Internal` state of the implementation should be initialised@@ -33,6 +34,7 @@  instance Equality Prim instance Eq Prim+instance Encodable Prim  instance Memory Internals instance Initialisable Internals (Key Prim)

@@ -10,8 +10,9 @@ -- -- 1. The `Prim` type captures the message digest and hence should be --    instances of `Eq`, so that we can compare messages by checking---    the digest, and `Equality`, so that the equality comparison can---    be made timing safe when part of a compound data.+--    the digest, `Equality`, so that the equality comparison can be+--    made timing safe when part of a compound data, and `Encodable`+--    so that we can serialise the digest into a byte string. -- -- 2. To start the process of computing the message digest the --    `Internal` state of the implementation should use initialised by@@ -31,6 +32,7 @@  instance Eq Prim instance Equality Prim+instance Encodable Prim  -- | The internal memory used by the primitive. data Internals

@@ -1,7 +1,7 @@ cabal-version: 3.0  name:    raaz-version: 0.3.4+version: 0.3.5 stability: experimental  synopsis: Fast and type safe cryptography.

@@ -50,6 +50,11 @@ -- convinced that the message could only have originated from a peer -- who knows @K@. --+-- == Serialisation+--+-- Message authentication tags are instances of `Encodable` and hence+-- can be serilised to byte strings.+-- -- == Warning -- -- Message authentication __does not__ provide secrecy of the message,

@@ -46,64 +46,34 @@ -- requires additional authenticated data. The `lockWith` and the -- `unlockWith` variants are used for this purpose. ----- == Key reuse.+-- == Safety against key reuse ----- Authenticated encryption needs, not just a key, but also a--- nounce. Under the hood, both `lock` and `lockWith` uses randomly--- generated nounce for each invocation (hence the result is an @IO@--- type). This ensures that the key-nounce pair is never reused. The--- nounce is packed together with the cipher text and tag so that at--- the receiving end, the packet can be unlocked. It is therefore safe--- to lock multiple messages with the same key.---- $aead$+-- The interface exposed here is safe /even with key reuse/. Under the+-- hood, both `lock` and `lockWith` uses randomly generated nounce for+-- each invocation (hence the result is an @IO@ type). The nounce is+-- large (192-bits) and is generated using cryptographically secure+-- pseudo-random generator (csprg). Thus even when a particular key is+-- used multiple times, each such invocation is paired with a distinct+-- nounce thereby preventing the reuse of the (key, nounce)-pair. ----- Some protocols have additional data that needs to be factored in--- when sending the locked packet. In such situations one can use the--- `lockWith` and `unlockWith` variants.----- $security$+-- == Serialisation ----- __WARNING:__ The security of the interface is compromised if+-- Unfortunately, there does not seem to be an agreed upon format for+-- serialising AEAD tokens. As a result the Locked type does not have+-- an instance of `Encodable` unlike the message digest and message+-- authentication type. However, for particular wire protocol, one can+-- take apart the AEAD token using the "Raaz.AuthEncrypt.Unsafe"+-- interface and individually serialise the constituents. ----- 1. The key gets revealed to the attacker or+-- == Security assumption ----- 2. In the case of the unsafe versions (`unsafeLock` and---    `unsafeLockWith`) which uses explicit nounce, if the same---    key/nounce pair is used to lock two different messages.+-- The security of the interface is compromised if and only if the key+-- gets exposed. Otherwise an adversary should not be able to read,+-- tamper or forge Locked data. ----- Nounces need not be private and may be exposed to the attacker. In--- fact, we pack the nounce with the locked message to make recovery--- at the receiving end simple. --- $specific$------ The library exposes the following two authenticated encryption algorithm------ * Raaz.AuthEncrypt.ChaCha20Poly1305--- * Raaz.AuthEncrypt.XChaCha20Poly1305------ of which the latter (XChaCha20Poly1305) is used by default. Both of--- these modules only provide the unsafe version. In the case of the--- former (ChaCha20Poly1305), the nounce is a bit too small (96-bits)--- and random generation has a nontrivial chance of collison. It is--- however, slightly faster and is safe to use when there is frequent--- key resets as in the case of network protocols. As with other cases--- we recommend the use of the default interface instead of the--- specific one when ever possible.------ $takingapart$+-- $aead$ ----- Values belonging to the `Locked` and `AEAD` types are meant to be--- used as opaque objects. While unlocking these types, we do not--- decrypt untill the tag is verified. This helps in quickly rejecting--- fake packets without wasting time on decryption and improves the--- security against DoS attacks. Taking apart the cipher text and the--- authentication token can lead to incorrect handling and hence is--- __not__ recommended in general. Nonetheless, when implementing--- protocols that use AEAD, we might want to build and take apart--- these types. We give now give functions for these unsafe operations--- on AEAD packets.+-- Some protocols have additional data that needs to be factored in+-- when sending the locked packet. In such situations one can use the+-- `lockWith` and `unlockWith` variants.

@@ -6,7 +6,7 @@ -- Stability   : experimental -- module Raaz.AuthEncrypt.Unsafe-       ( -- * Auth Encryption with Explicit Nounce+       ( -- * Explicit computation and taking apart          -- $unsafe$          -- ** Specific variants          -- $specific$@@ -17,6 +17,17 @@  -- $unsafe$ --+-- This module provides two class of unsafe functions:+--+-- 1. Functions to compute AEAD tokens with explicit key and Nounce+--+-- 2. Functions to take apart an AEAD token into their constituents, namely+--    the nounce used, the cipher text, and the authentication tag.+--+-- The former is to help interface with other libraries where as the+-- latter allows us to serialise AEAD tokens.+--+-- -- __WARNING:__ The security of the interface is compromised if -- -- 1. The key gets revealed to the attacker or@@ -24,17 +35,12 @@ -- 2. If the same key/nounce pair is used to lock two different --    messages. ----- 3. Taking apart the AEAD token also compromises the type safety.------ Why then do we provide these functions ? As long as you are using--- the raaz library exclusively, you do not need to use this unsafe--- function. These are only needed when working with other libraries--- and protocols which have a different nonunce selection policy--- and/or a different encoding scheme for the AEAD token.+-- 3. Taking apart the AEAD token may compromises type safety. ----- Nounces need not be private and may be exposed to the attacker. In--- fact, in the safe version of these locking function, we pick the--- nounce at random (using the csprg) and pack it into the AEAD token.+-- Nounces /need not/ be private and may be exposed to the+-- attacker. In fact, in the safe version of these locking function,+-- we pick the nounce at random (using the csprg) and pack it into the+-- AEAD token.  -- $specific$ --

@@ -65,6 +65,12 @@ -- There are three variants for computing the digest of a -- message. `digest`, `digestFile` and `digestSource`. --+-- === Serialisation+--+-- Digests are instances of `Encodable` and hence can be serialised+-- directly to byte string.+--+-- -- == Warning -- -- Message digests __DO NOT__ provide any authentication; any one

@@ -9,7 +9,7 @@        ( Locked        , unsafeLock, unsafeLockWith        , Cipher, AuthTag-       , unsafeToCipherText, unsafeToAuthTag+       , unsafeToNounce, unsafeToCipherText, unsafeToAuthTag        , unsafeLocked        ) where @@ -62,6 +62,9 @@ unsafeToAuthTag :: Locked -> AE.AuthTag unsafeToAuthTag = AE.unsafeToAuthTag +-- | Get the nounce used for authenticating the token.+unsafeToNounce :: Locked -> Nounce Cipher+unsafeToNounce = AE.unsafeToNounce  -- | Construct the locked message out of the nounce, cipher text, and the -- authentication tag.