diff --git a/Crypto/Random/API.hs b/Crypto/Random/API.hs new file mode 100644 --- /dev/null +++ b/Crypto/Random/API.hs @@ -0,0 +1,73 @@ +-- | +-- Module : Crypto.Random.API +-- License : BSD-style +-- Maintainer : Vincent Hanquez +-- Stability : experimental +-- Portability : Good + +module Crypto.Random.API + ( CPRG(..) + , genRandomBytes + , withRandomBytes + , getSystemEntropy + ) where + +import qualified Data.ByteString as B +import Data.ByteString (ByteString) +import System.Entropy (getEntropy) + +-- | A class of Cryptographic Secure Random generator. +-- +-- The main difference with the generic haskell RNG is that +-- it return bytes instead of integer. +-- +-- It is quite similar to the CryptoRandomGen class in crypto-api +-- except that error are not returned to the user. Instead +-- the user is suppose to handle reseeding by using the NeedReseed +-- and SupplyEntropy methods. For other type of errors, the user +-- is expect to generate bytes with the parameters bounds explicity +-- defined here. +-- +-- The CPRG need to be able to generate up to 2^20 bytes in one call, +-- +class CPRG g where + -- | Provide a way to query the CPRG to calculate when new entropy + -- is required to be supplied so the CPRG doesn't repeat output, and + -- break assumptions. This returns the number of bytes before + -- which supply entropy should have been called. + cprgNeedReseed :: g -> Int + + -- | Supply entropy to the CPRG, that can be used now or later + -- to reseed the CPRG. This should be used in conjunction to + -- NeedReseed to know when to supply entropy. + cprgSupplyEntropy :: g -> ByteString -> g + + -- | Generate bytes using the CPRG and the number specified. + -- + -- For user of the API, it's recommended to use genRandomBytes + -- instead of this method directly. + cprgGenBytes :: g -> Int -> (ByteString, g) + +-- | Generate bytes using the cprg in parameter. +-- +-- arbitrary limit the number of bytes that can be generated in +-- one go to 10mb. +genRandomBytes :: CPRG g => g -- ^ CPRG to use + -> Int -- ^ number of bytes to return + -> (ByteString, g) +genRandomBytes rng len + | len < 0 = error "genBytes: cannot request negative amount of bytes." + | len > 2^20 = error "genBytes: cannot request more than 1mb of bytes in one go." + | len == 0 = (B.empty, rng) + | otherwise = cprgGenBytes rng len + +-- | this is equivalent to using Control.Arrow 'first' with genBytes. +-- +-- namely it generate @len bytes and map the bytes to the function @f +withRandomBytes :: CPRG g => g -> Int -> (ByteString -> a) -> (a, g) +withRandomBytes rng len f = (f bs, rng') + where (bs, rng') = genRandomBytes rng len + +-- | Return system entropy using the entropy package 'getEntropy' +getSystemEntropy :: Int -> IO ByteString +getSystemEntropy = getEntropy diff --git a/LICENSE b/LICENSE new file mode 100644 --- /dev/null +++ b/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2010-2012 Vincent Hanquez + +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. +3. Neither the name of the author nor the names of his contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. diff --git a/Setup.hs b/Setup.hs new file mode 100644 --- /dev/null +++ b/Setup.hs @@ -0,0 +1,2 @@ +import Distribution.Simple +main = defaultMain diff --git a/crypto-random-api.cabal b/crypto-random-api.cabal new file mode 100644 --- /dev/null +++ b/crypto-random-api.cabal @@ -0,0 +1,23 @@ +Name: crypto-random-api +Version: 0.1.0 +Description: Simple random generators API for cryptography related code +License: BSD3 +License-file: LICENSE +Copyright: Vincent Hanquez +Author: Vincent Hanquez +Maintainer: Vincent Hanquez +Synopsis: Simple random generators API for cryptography related code +Category: Cryptography +Build-Type: Simple +Homepage: http://github.com/vincenthz/hs-crypto-random-api +Cabal-Version: >=1.6 + +Library + Exposed-modules: Crypto.Random.API + Build-depends: base >= 4 && < 5 + , bytestring + , entropy + +source-repository head + type: git + location: git://github.com/vincenthz/hs-crypto-random-api