diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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]: [0.3.1]: [0.3.2]: +[0.3.3]: +[0.3.4]: +[0.3.5]: [raaz]: diff --git a/api/aead/Auth/Implementation.hsig b/api/aead/Auth/Implementation.hsig --- a/api/aead/Auth/Implementation.hsig +++ b/api/aead/Auth/Implementation.hsig @@ -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 diff --git a/api/aead/Cipher/Implementation.hsig b/api/aead/Cipher/Implementation.hsig --- a/api/aead/Cipher/Implementation.hsig +++ b/api/aead/Cipher/Implementation.hsig @@ -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 diff --git a/api/auth/Implementation.hsig b/api/auth/Implementation.hsig --- a/api/auth/Implementation.hsig +++ b/api/auth/Implementation.hsig @@ -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) diff --git a/api/digest/Implementation.hsig b/api/digest/Implementation.hsig --- a/api/digest/Implementation.hsig +++ b/api/digest/Implementation.hsig @@ -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 diff --git a/raaz.cabal b/raaz.cabal --- a/raaz.cabal +++ b/raaz.cabal @@ -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. diff --git a/raaz/Raaz/Auth.hs b/raaz/Raaz/Auth.hs --- a/raaz/Raaz/Auth.hs +++ b/raaz/Raaz/Auth.hs @@ -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, diff --git a/raaz/Raaz/AuthEncrypt.hs b/raaz/Raaz/AuthEncrypt.hs --- a/raaz/Raaz/AuthEncrypt.hs +++ b/raaz/Raaz/AuthEncrypt.hs @@ -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. diff --git a/raaz/Raaz/AuthEncrypt/Unsafe.hs b/raaz/Raaz/AuthEncrypt/Unsafe.hs --- a/raaz/Raaz/AuthEncrypt/Unsafe.hs +++ b/raaz/Raaz/AuthEncrypt/Unsafe.hs @@ -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$ -- diff --git a/raaz/Raaz/Digest.hs b/raaz/Raaz/Digest.hs --- a/raaz/Raaz/Digest.hs +++ b/raaz/Raaz/Digest.hs @@ -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 diff --git a/raaz/Raaz/V1/AuthEncrypt/Unsafe.hs b/raaz/Raaz/V1/AuthEncrypt/Unsafe.hs --- a/raaz/Raaz/V1/AuthEncrypt/Unsafe.hs +++ b/raaz/Raaz/V1/AuthEncrypt/Unsafe.hs @@ -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.