Copyright	(c) Joseph Abrahamson 2013
License	MIT
Maintainer	me@jspha.com
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Crypto.Saltine.Core.Stream

Description

Secret-key encryption: Crypto.Saltine.Core.Stream

The stream function produces a sized stream ByteString as a function of a secret key and a nonce. The xor function encrypts a message ByteString using a secret key and a nonce. The xor function guarantees that the ciphertext has the same length as the plaintext, and is the plaintext xor stream k n. Consequently xor can also be used to decrypt.

The stream function, viewed as a function of the nonce for a uniform random key, is designed to meet the standard notion of unpredictability ("PRF"). For a formal definition see, e.g., Section 2.3 of Bellare, Kilian, and Rogaway, "The security of the cipher block chaining message authentication code," Journal of Computer and System Sciences 61 (2000), 362–399; http://www-cse.ucsd.edu/~mihir/papers/cbc.html. This means that an attacker cannot distinguish this function from a uniform random function. Consequently, if a series of messages is encrypted by xor with a different nonce for each message, the ciphertexts are indistinguishable from uniform random strings of the same length.

Note that the length is not hidden. Note also that it is the caller's responsibility to ensure the uniqueness of nonces—for example, by using nonce 1 for the first message, nonce 2 for the second message, etc. Nonces are long enough that randomly generated nonces have negligible risk of collision.

Saltine does not make any promises regarding the resistance of crypto_stream to "related-key attacks." It is the caller's responsibility to use proper key-derivation functions.

Crypto.Saltine.Core.Stream is crypto_stream_xsalsa20, a particular cipher specified in "Cryptography in NaCl" (http://nacl.cr.yp.to/valid.html), Section 7. This cipher is conjectured to meet the standard notion of unpredictability.

This is version 2010.08.30 of the stream.html web page.

Synopsis

data Key
data Nonce
newKey :: IO Key
newNonce :: IO Nonce
stream :: Key -> Nonce -> Int -> ByteString
xor :: Key -> Nonce -> ByteString -> ByteString

Documentation

data Key Source #

An opaque stream cryptographic key.

Instances

Instances details

Eq Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods (==) :: Key -> Key -> Bool # (/=) :: Key -> Key -> Bool #
Data Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Key -> c Key # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Key # toConstr :: Key -> Constr # dataTypeOf :: Key -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Key) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Key) # gmapT :: (forall b. Data b => b -> b) -> Key -> Key # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Key -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Key -> r # gmapQ :: (forall d. Data d => d -> u) -> Key -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Key -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Key -> m Key # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Key -> m Key # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Key -> m Key #
Ord Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods compare :: Key -> Key -> Ordering # (<) :: Key -> Key -> Bool # (<=) :: Key -> Key -> Bool # (>) :: Key -> Key -> Bool # (>=) :: Key -> Key -> Bool # max :: Key -> Key -> Key # min :: Key -> Key -> Key #
Show Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods showsPrec :: Int -> Key -> ShowS # show :: Key -> String # showList :: [Key] -> ShowS #
Generic Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Associated Types type Rep Key :: Type -> Type # Methods from :: Key -> Rep Key x # to :: Rep Key x -> Key #
NFData Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods rnf :: Key -> () #
Hashable Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods hashWithSalt :: Int -> Key -> Int # hash :: Key -> Int #
IsEncoding Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods encode :: Key -> ByteString Source # decode :: ByteString -> Maybe Key Source # encoded :: (Choice p, Applicative f) => p Key (f Key) -> p ByteString (f ByteString) Source #
type Rep Key Source #
Instance details Defined in Crypto.Saltine.Internal.Stream type Rep Key = D1 ('MetaData "Key" "Crypto.Saltine.Internal.Stream" "saltine-0.2.0.1-inplace" 'True) (C1 ('MetaCons "Key" 'PrefixI 'True) (S1 ('MetaSel ('Just "unKey") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

data Nonce Source #

An opaque stream nonce.

Instances

Instances details

Eq Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods (==) :: Nonce -> Nonce -> Bool # (/=) :: Nonce -> Nonce -> Bool #
Data Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Nonce -> c Nonce # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Nonce # toConstr :: Nonce -> Constr # dataTypeOf :: Nonce -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Nonce) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Nonce) # gmapT :: (forall b. Data b => b -> b) -> Nonce -> Nonce # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Nonce -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Nonce -> r # gmapQ :: (forall d. Data d => d -> u) -> Nonce -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Nonce -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Nonce -> m Nonce # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Nonce -> m Nonce # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Nonce -> m Nonce #
Ord Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods compare :: Nonce -> Nonce -> Ordering # (<) :: Nonce -> Nonce -> Bool # (<=) :: Nonce -> Nonce -> Bool # (>) :: Nonce -> Nonce -> Bool # (>=) :: Nonce -> Nonce -> Bool # max :: Nonce -> Nonce -> Nonce # min :: Nonce -> Nonce -> Nonce #
Show Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods showsPrec :: Int -> Nonce -> ShowS # show :: Nonce -> String # showList :: [Nonce] -> ShowS #
Generic Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Associated Types type Rep Nonce :: Type -> Type # Methods from :: Nonce -> Rep Nonce x # to :: Rep Nonce x -> Nonce #
NFData Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods rnf :: Nonce -> () #
Hashable Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods hashWithSalt :: Int -> Nonce -> Int # hash :: Nonce -> Int #
IsNonce Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods zero :: Nonce Source # nudge :: Nonce -> Nonce Source #
IsEncoding Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream Methods encode :: Nonce -> ByteString Source # decode :: ByteString -> Maybe Nonce Source # encoded :: (Choice p, Applicative f) => p Nonce (f Nonce) -> p ByteString (f ByteString) Source #
type Rep Nonce Source #
Instance details Defined in Crypto.Saltine.Internal.Stream type Rep Nonce = D1 ('MetaData "Nonce" "Crypto.Saltine.Internal.Stream" "saltine-0.2.0.1-inplace" 'True) (C1 ('MetaCons "Nonce" 'PrefixI 'True) (S1 ('MetaSel ('Just "unNonce") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ByteString)))

newKey :: IO Key Source #

Creates a random key of the correct size for stream and xor.

newNonce :: IO Nonce Source #

Creates a random nonce of the correct size for stream and xor.

stream Source #

Arguments

:: Key
-> Nonce
-> Int
-> ByteString	Cryptographic stream

Generates a cryptographic random stream indexed by the Key and Nonce. These streams are indistinguishable from random noise so long as the Nonce is not used more than once.

xor Source #

Arguments

:: Key
-> Nonce
-> ByteString	Message
-> ByteString	Ciphertext

Computes the exclusive-or between a message and a cryptographic random stream indexed by the Key and the Nonce. This renders the output indistinguishable from random noise so long as the Nonce is not used more than once. Note: while this can be used for encryption and decryption, it is possible for an attacker to manipulate the message in transit without detection. USE AT YOUR OWN RISK.