-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A generic interface for cryptographic operations
--   
--   A generic interface for cryptographic operations, platform independent
--   quality RNG, property tests and known-answer tests (KATs) for common
--   algorithms, and a basic benchmark infrastructure. Maintainers of hash
--   and cipher implementations are encouraged to add instances for the
--   classes defined in Crypto.Classes. Crypto users are similarly
--   encouraged to use the interfaces defined in the Classes module. Any
--   concepts or functions of general use to more than one cryptographic
--   algorithm (ex: padding) is within scope of this package.
@package crypto-api
@version 0.0.0.2


-- | Provides Word128, Word192 and Word256 and a way of producing other
--   large words if required.
module Data.LargeWord
data LargeKey a b
type Word96 = LargeKey Word32 Word64
type Word128 = LargeKey Word64 Word64
type Word160 = LargeKey Word32 Word128
type Word192 = LargeKey Word64 Word128
type Word224 = LargeKey Word32 Word192
type Word256 = LargeKey Word64 Word192
instance (Eq a, Eq b) => Eq (LargeKey a b)
instance (Ord a, Ord b) => Ord (LargeKey a b)
instance Enum (LargeKey a b)
instance (Ord a, Bits a, LargeWord a, Ord b, Bits b, LargeWord b) => Real (LargeKey a b)
instance (Ord a, Bits a, LargeWord a, Ord b, Bits b, LargeWord b) => Integral (LargeKey a b)
instance (Ord a, Bits a, Bounded a, Integral a, LargeWord a, Bits b, Bounded b, Integral b, LargeWord b) => Bounded (LargeKey a b)
instance (Ord a, Bits a, LargeWord a, Bits b, LargeWord b) => Bits (LargeKey a b)
instance (Ord a, Bits a, LargeWord a, Bits b, LargeWord b) => Num (LargeKey a b)
instance (Ord a, Bits a, LargeWord a, Bits b, LargeWord b) => Show (LargeKey a b)
instance (Ord a, Bits a, LargeWord a, Bits b, LargeWord b) => LargeWord (LargeKey a b)
instance LargeWord Word64
instance LargeWord Word32

module Crypto.Types
type BitLength = Int
type ByteLength = Int


-- | Obtain entropy from system sources. This module is rather untested on
--   Windows (or testers never provided feedback), though testing was
--   requested from the community - please e-mail the maintainer with test
--   results.
module System.Crypto.Random

-- | Inefficiently get a specific number of bytes of cryptographically
--   secure random data using the system-specific facilities.
--   
--   Use '/dev/urandom' on *nix and CryptAPI when on Windows.
getEntropy :: ByteLength -> IO ByteString

-- | Handle for manual resource mangement
data CryptHandle

-- | Open a <a>CryptHandle</a>
openHandle :: IO CryptHandle

-- | Read random data from a <a>CryptHandle</a>
hGetEntropy :: CryptHandle -> Int -> IO ByteString

-- | Close the <a>CryptHandle</a>
closeHandle :: CryptHandle -> IO ()


-- | This module is for instantiating cryptographically strong determinitic
--   random bit generators (DRBGs, aka PRNGs) For the simple use case of
--   using the system random number generator
--   (<tt>System.Crypto.Random</tt>) to seed the DRBG:
--   
--   <pre>
--   g &lt;- newGenIO
--   </pre>
--   
--   Users needing to provide their own entropy can call <a>newGen</a>
--   directly
--   
--   <pre>
--   entropy &lt;- getEntropy nrBytes
--   let generator = newGen entropy
--   </pre>
module Crypto.Random

-- | Any <a>CryptoRandomGen</a> can be used where the <a>RandomGen</a>
--   class is needed simply by wrapping with with the <a>AsRG</a>
--   constructor. Any failures (Left results from genBytes or newGen)
--   result in a pattern match exception. Such failures were simply assumed
--   not possible by the <a>RandomGen</a> class, hence there is no
--   non-exception way to indicate a failure.
data AsRandomGen a
AsRG :: a -> AsRandomGen a

-- | A class of random bit generators that allows for the possibility of
--   failure, reseeding, providing entropy at the same time as requesting
--   bytes
--   
--   Minimum complete definition: <a>newGen</a>, <a>genSeedLength</a>,
--   <a>genBytes</a>, <a>reseed</a>.
class CryptoRandomGen g
newGen :: (CryptoRandomGen g) => ByteString -> Either GenError g
genSeedLength :: (CryptoRandomGen g) => Tagged g ByteLength
genBytes :: (CryptoRandomGen g) => g -> ByteLength -> Either GenError (ByteString, g)
genBytesWithEntropy :: (CryptoRandomGen g) => g -> ByteLength -> ByteString -> Either GenError (ByteString, g)
reseed :: (CryptoRandomGen g) => g -> ByteString -> Either GenError g

-- | <tt>genInteger g (low,high)</tt> will generate an integer between
--   [low, high] inclusively, swapping the pair if high &lt; low.
--   
--   This function has degraded (theoretically unbounded, probabilitically
--   decent) performance the closer your range size (high - low) is to 2^n
--   (from the top).
genInteger :: (CryptoRandomGen g) => g -> (Integer, Integer) -> Either GenError (Integer, g)

-- | many generators have these error conditions in common
data GenError

-- | Misc
GenErrorOther :: String -> GenError

-- | Requested more bytes than a single pass can generate (ex: genBytes g i
--   | i &gt; 2^(2^32))
RequestedTooManyBytes :: GenError

-- | When using <tt>genInteger g (l,h)</tt> and <tt>logBase 2 (h - l) &gt;
--   (maxBound :: Int)</tt>.
RangeInvalid :: GenError

-- | Some generators cease operation after too high a count without a
--   reseed (ex: NIST SP 800-90)
NeedReseed :: GenError

-- | For instantiating new generators (or reseeding)
NotEnoughEntropy :: GenError

-- | Use <a>System.Crypto.Random</a> to obtain entropy for <a>newGen</a>.
newGenIO :: (CryptoRandomGen g) => IO g
instance (Eq a) => Eq (AsRandomGen a)
instance (Ord a) => Ord (AsRandomGen a)
instance (Show a) => Show (AsRandomGen a)
instance Eq GenError
instance Ord GenError
instance Show GenError
instance (SplittableGen g, CryptoRandomGen g) => RandomGen (AsRandomGen g)


-- | This is the heart of the crypto-api package. By making (or having) an
--   instance of Hash, AsymCipher, BlockCipher or StreamCipher you provide
--   (or obtain) access to any infrastructure built on these primitives
--   include block cipher modes of operation, hashing, hmac, signing, etc.
--   These classes allow users to build routines that are agnostic to the
--   algorithm used so changing algorithms is as simple as changing a type
--   signature.
module Crypto.Classes

-- | The Hash class is intended as the generic interface targeted by
--   maintainers of Haskell digest implementations. Using this generic
--   interface, higher level functions such as <a>hash</a> and <a>hash'</a>
--   provide a useful API for comsumers of hash implementations.
--   
--   Any instantiated implementation must handle unaligned data
class (Binary d, Serialize d, Eq d, Ord d) => Hash ctx d | d -> ctx, ctx -> d
outputLength :: (Hash ctx d) => Tagged d BitLength
blockLength :: (Hash ctx d) => Tagged d BitLength
initialCtx :: (Hash ctx d) => ctx
updateCtx :: (Hash ctx d) => ctx -> ByteString -> ctx
finalize :: (Hash ctx d) => ctx -> ByteString -> d

-- | The BlockCipher class is intended as the generic interface targeted by
--   maintainers of Haskell cipher implementations. Using this generic
--   interface higher level functions such as <tt>cbc</tt>, and other
--   functions from Data.Crypto.Modes, provide a useful API for comsumers
--   of cipher implementations.
--   
--   Instances must handle unaligned data
class (Binary k, Serialize k) => BlockCipher k
blockSize :: (BlockCipher k) => Tagged k BitLength
encryptBlock :: (BlockCipher k) => k -> ByteString -> ByteString
decryptBlock :: (BlockCipher k) => k -> ByteString -> ByteString
buildKey :: (BlockCipher k) => ByteString -> Maybe k
keyLength :: (BlockCipher k) => k -> BitLength

-- | A stream cipher class. Instance are expected to work on messages as
--   small as one byte The length of the resulting cipher text should be
--   equal to the length of the input message.
class (Binary k, Serialize k) => StreamCipher k iv | k -> iv
buildStreamKey :: (StreamCipher k iv) => ByteString -> Maybe k
encryptStream :: (StreamCipher k iv) => k -> iv -> ByteString -> (ByteString, iv)
decryptStream :: (StreamCipher k iv) => k -> iv -> ByteString -> (ByteString, iv)
streamKeyLength :: (StreamCipher k iv) => k -> BitLength
class (Binary p, Serialize p) => AsymCipher p
buildKeyPair :: (AsymCipher p, CryptoRandomGen g) => g -> BitLength -> Maybe ((p, p), g)
encryptAsym :: (AsymCipher p) => p -> ByteString -> ByteString
decryptAsym :: (AsymCipher p) => p -> ByteString -> ByteString
asymKeyLength :: (AsymCipher p) => p -> BitLength

-- | Obtain a tagged value for a given type
for :: Tagged a b -> a -> b

-- | Infix <a>for</a> operator
(.::.) :: Tagged a b -> a -> b

-- | Hash a lazy ByteString, creating a digest
hash :: (Hash ctx d) => ByteString -> d

-- | Hash a strict ByteString, creating a digest
hash' :: (Hash ctx d) => ByteString -> d

-- | Obtain a lazy hash function from a digest
hashFunc :: (Hash c d) => d -> (ByteString -> d)

-- | Obtain a strict hash function from a digest
hashFunc' :: (Hash c d) => d -> (ByteString -> d)


module Crypto.HMAC

-- | Message authentication code calculation for lazy bytestrings. <tt>hmac
--   k msg</tt> will compute an authentication code for <tt>msg</tt> using
--   key <tt>k</tt>
hmac :: (Hash c d) => MacKey -> ByteString -> d

-- | <tt>hmac k msg</tt> will compute an authentication code for
--   <tt>msg</tt> using key <tt>k</tt>
hmac' :: (Hash c d) => MacKey -> ByteString -> d
newtype MacKey
MacKey :: ByteString -> MacKey
instance Eq MacKey
instance Ord MacKey
instance Show MacKey


-- | Generic mode implementations useable by any correct BlockCipher
--   instance
--   
--   Be aware there are no tests for CFB mode yet. See <a>Test.Crypto</a>.
module Crypto.Modes
ecb :: (BlockCipher k) => k -> ByteString -> ByteString
unEcb :: (BlockCipher k) => k -> ByteString -> ByteString

-- | Cipher block chaining encryption for lazy bytestrings
cbc :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Cipher block chaining decryption for lazy bytestrings
unCbc :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Ciphertext feed-back encryption mode for lazy bytestrings (with s ==
--   blockSize)
cfb :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Ciphertext feed-back decryption mode for lazy bytestrings (with s ==
--   blockSize)
unCfb :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Output feedback mode for lazy bytestrings
ofb :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Output feedback mode for lazy bytestrings
unOfb :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)
ecb' :: (BlockCipher k) => k -> ByteString -> ByteString
unEcb' :: (BlockCipher k) => k -> ByteString -> ByteString

-- | zipWith xor + Pack This is written intentionally to take advantage of
--   the bytestring libraries <tt>zipWith'</tt> rewrite rule but at the
--   extra cost of the resulting lazy bytestring being more fragmented than
--   either of the two inputs.
--   
--   zipWith xor + Pack As a result of rewrite rules, this should
--   automatically be optimized (at compile time) to use the bytestring
--   libraries <tt>zipWith'</tt> function.
--   
--   Cipher block chaining encryption mode on strict bytestrings
cbc' :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Cipher block chaining decryption for strict bytestrings
unCbc' :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Ciphertext feed-back encryption mode for strict bytestrings (with s ==
--   blockSize)
cfb' :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Ciphertext feed-back decryption mode for strict bytestrings (with s ==
--   blockSize)
unCfb' :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Output feedback mode for strict bytestrings
ofb' :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Output feedback mode for strict bytestrings
unOfb' :: (BlockCipher k) => k -> IV k -> ByteString -> (ByteString, IV k)

-- | Initilization Vectors for BlockCipher implementations (IV k) are used
--   for various modes and guarrenteed to be blockSize bits long.
data IV k

-- | Obtain an <a>IV</a> using the provided CryptoRandomGenerator.
getIV :: (BlockCipher k, CryptoRandomGen g) => g -> Either GenError (IV k, g)

-- | Obtain an <a>IV</a> using the system entropy (see
--   <a>System.Crypto.Random</a>)
getIVIO :: (BlockCipher k) => IO (IV k)
instance Eq (IV k)
instance Ord (IV k)
instance Show (IV k)
instance (BlockCipher k) => Binary (IV k)
instance (BlockCipher k) => Serialize (IV k)