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


-- | Elliptic Curve Cryptography for Haskell
--   
--   Elliptic Curve Cryptography in Haskell, evolved for correctness and
--   practical usability from higher-level libraries.
--   
--   The implementation is pure Haskell and as generic and fast as
--   reasonably possible. Timing-attack resistance is important, failure
--   must be documented.
--   
--   This library was formerly known and its code originated as hecc, but
--   since this would imply Hyperelliptic ECC, the name was changed.
--   
--   Also the scope was changed by selecting best internal formats and no
--   longer trying to be overly general, allowing more optimizations.
--   
--   N.B.: F2 is faulty and slow.
--   
--   More secure curves will be added.
@package eccrypto
@version 0.0


-- | ECC Base algorithms & point formats for NIST Curves as specified
--   in
--   NISTReCur.pdf[http:/<i>csrc.nist.gov</i>groups<i>ST</i>toolkit<i>documents</i>dss/NISTReCur.pdf]
--   Re Timing-Attacks: We depend on (==) being resistant for Integer.
module Crypto.Common

-- | return the maximum value storable in a Word
wordMax :: (Integral a) => a

-- | return the bitSize of a Word
wordSize :: Int

-- | determine the needed storage for a bitlength in Words
sizeinWords :: Int -> Int

-- | a vector of zeros of requested length
zero :: Int -> Vector Word

-- | a vector of zeros of requested length, but least significant word 1
one :: Int -> Vector Word

-- | a vector of zeros of requested length, but least significant word 2
two :: Int -> Vector Word

-- | a vector of zeros of requested length, but least significant word 3
three :: Int -> Vector Word

-- | returning the binary length of an Integer
log2len :: (Integral a, Bits a) => a -> Int

-- | we want word w at position i to result in a word to multiply by,
--   eliminating branching
testcond :: Word -> Int -> Word


-- | Functions for F_{2^{E}} Re Timing-Attacks: We depend on (==) being
--   resistant for Integer. This backend is faulty and slow.
module Crypto.F2

-- | F2 consist of an exact length of meaningful bits and a representation
--   of those bits in a possibly larger Vector of Words | Note: The vectors
--   use small to large indices, but the Data.Word endianness is of no
--   concern as it is hidden by Data.Bits | This results in indices from 0
--   to l-1 mapped from left to right across Words | Be careful with those
--   indices! The usage of quotRem with them has caused some headache.
data F2
F2 :: {-# UNPACK #-} !Int -> !(Vector Word) -> F2

-- | (==) on F2
eq :: F2 -> F2 -> Bool

-- | (+) on F2
add :: F2 -> F2 -> F2

-- | (+) on F2 modulo p
addr :: F2 -> F2 -> F2 -> F2

-- | shift on F2
shift :: F2 -> Int -> F2

-- | (*) on F2 peasants algorithm
mul :: F2 -> F2 -> F2

-- | (*) on F2, reduced to stay in the field
mulr :: F2 -> F2 -> F2 -> F2

-- | testBit on F2
testBit :: F2 -> Int -> Bool

-- | polynomial reduction, simple scan TODO: idempotent? not right now
--   -&gt; ERROR!
redc :: F2 -> F2 -> F2

-- | squaring on F2 TODO: optimize
square :: F2 -> F2

-- | the power function on F2 for positive exponents, reducing early
pow :: (Bits a, Integral a) => F2 -> F2 -> a -> F2

-- | inversion of F2 in the field
inv :: F2 -> F2 -> F2

-- | this is a chunked converter from Integer into eccrypto native format
--   TODO: implement low-level Integer conversion?
fromInteger :: Int -> Integer -> F2

-- | this is a chunked converter from eccrypto native format into Integer
--   TODO: implement low-level Integer conversion?
toInteger :: F2 -> Integer
instance GHC.Show.Show Crypto.F2.F2


-- | This is a thin wrapper around Integer to ease transition toward FPrime
--   WARNING! Re Timing-Attacks: This backend is not fully timing attack
--   resistant.
module Crypto.Fi

-- | a simple wrapper to ease transition
type FPrime = Integer

-- | most trivial (==) wrapper
eq :: FPrime -> FPrime -> Bool

-- | (+) in the field
add :: FPrime -> FPrime -> FPrime

-- | (+) in the field
addr :: FPrime -> FPrime -> FPrime -> FPrime

-- | (-) in the field
sub :: FPrime -> FPrime -> FPrime

-- | (-) in the field
subr :: FPrime -> FPrime -> FPrime -> FPrime

-- | negation in the field
neg :: FPrime -> FPrime -> FPrime

-- | bitshift wrapper
shift :: FPrime -> Int -> FPrime

-- | field multiplication, a * b
mul :: FPrime -> FPrime -> FPrime

-- | field multiplication, a * b <a>mod</a> p
mulr :: FPrime -> FPrime -> FPrime -> FPrime

-- | modular reduction, a simple wrapper around mod
redc :: FPrime -> FPrime -> FPrime

-- | simple squaring in the field
square :: FPrime -> FPrime -> FPrime

-- | the power function in the field
pow :: (Bits a, Integral a) => FPrime -> FPrime -> a -> FPrime

-- | field inversion
inv :: FPrime -> FPrime -> FPrime

-- | conversion wrapper with a limit
fromInteger :: Int -> FPrime -> Integer

-- | a most simple conversion wrapper
toInteger :: FPrime -> Integer

-- | a testBit wrapper
testBit :: FPrime -> Int -> Bool

-- | like testBit, but give either 0 or 1
condBit :: FPrime -> Int -> FPrime


-- | Long-time plan: get rid of Integer and do all field arithmetic
--   const-time by hand
module Crypto.ECC.Ed25519.EdDSA

-- | working on exactly 256 bits
b :: Int

-- | the large prime
q :: FPrime

-- | curve parameter l
l :: FPrime

-- | curve parameter d
d :: FPrime

-- | sqrt (-1) on our curve
i :: FPrime

-- | wrapper for our hash function
h :: ByteString -> ByteString

-- | the y coordinate of the base point of the curve
by :: FPrime
inf :: Point

-- | special form of FPrime, no bits set
null :: FPrime

-- | special form of FPrime, lowest bit set
eins :: FPrime

-- | special form of FPrime, all bits set
alleeins :: FPrime

-- | recover the x coordinate from the y coordinate and a signum
xrecover :: FPrime -> Integer -> FPrime

-- | convert a FPrime to a list of FPrimes, each 0 or 1 depending on the
--   inputs bits
listofbits :: FPrime -> [FPrime]

-- | base point on the curve
bPoint :: Point

-- | scalar addition
padd :: Point -> Point -> Point

-- | scalar multiplication, branchfree in k, pattern-matched branch on j
--   (length of k)
pmul :: Point -> FPrime -> Point

-- | check if Point is on the curve, prevents some attacks
ison :: Point -> Bool

-- | converts 32 little endian bytes into one FPrime
getFPrime :: Get FPrime

-- | converts one FPrime into exactly 32 little endian bytes
putFPrime :: FPrime -> Put

-- | convert a point on the curve to a ByteString
pointtobs :: Point -> ByteString

-- | convert a ByteString to a point on the curve
bstopoint :: ByteString -> Either String Point

-- | multiply the curve base point by a FPrime, giving a point on the curve
keyPoint :: SecFPrime -> PubKeyPoint
a :: SecKey -> Either String SecFPrime
data Point
Point :: (FPrime, FPrime) -> Point
data VerifyResult
SigOK :: VerifyResult
SigBad :: VerifyResult
type PubKey = ByteString
type PubKeyPoint = Point
type SecKey = ByteString
type SecFPrime = FPrime
type Signature = ByteString
type Message = ByteString

-- | generate a new key pair (secret and derived public key) using some
--   external entropy
genkeys_simple :: IO (Either String (SecKey, PubKey))

-- | generate a new key pair (secret and derived public key) using the
--   supplied randomness-generator
genkeys :: (CryptoRandomGen g) => g -> (Either String (SecKey, PubKey))

-- | sign with secret key the message, resulting in message appended to the
--   signature
sign :: SecKey -> Message -> Either String Signature

-- | sign with secret key the message, resulting in a detached signature
sign_detached :: SecKey -> Message -> Either String Signature
instance GHC.Show.Show Crypto.ECC.Ed25519.EdDSA.VerifyResult
instance GHC.Classes.Eq Crypto.ECC.Ed25519.EdDSA.VerifyResult
instance GHC.Show.Show Crypto.ECC.Ed25519.EdDSA.Point
instance GHC.Classes.Eq Crypto.ECC.Ed25519.EdDSA.Point


-- | ECC Base algorithms &amp; point formats for NIST Curves as specified
--   in
--   NISTReCur.pdf[http:/<i>csrc.nist.gov</i>groups<i>ST</i>toolkit<i>documents</i>dss/NISTReCur.pdf]
--   Re Timing-Attacks: The field backends differ in timing-attack
--   resistance. Due to the nature of NIST-curves, there are pitfalls in
--   this module.
module Crypto.ECC.NIST.Base

-- | a simple wrapper to ease transition
type FPrime = Integer

-- | F2 consist of an exact length of meaningful bits and a representation
--   of those bits in a possibly larger Vector of Words | Note: The vectors
--   use small to large indices, but the Data.Word endianness is of no
--   concern as it is hidden by Data.Bits | This results in indices from 0
--   to l-1 mapped from left to right across Words | Be careful with those
--   indices! The usage of quotRem with them has caused some headache.
data F2

-- | all Elliptic Curves, the parameters being the BitLength L, A, B and P
data EC a
[ECi] :: Int -> FPrime -> FPrime -> FPrime -> EC FPrime
[ECb] :: Int -> Int -> F2 -> F2 -> FPrime -> EC F2

-- | data of Elliptic Curve Points
data ECPF a
[ECPp] :: FPrime -> FPrime -> FPrime -> ECPF FPrime
[ECPpF2] :: F2 -> F2 -> F2 -> ECPF F2

-- | generic getter, returning the affine x and y-value
affine :: EC a -> ECPF a -> (a, a)

-- | translate point in internal format to a pair of Integers in affine x
--   and y coordinate | this is intended as interface to other libraries
export :: EC a -> ECPF a -> (Integer, Integer)

-- | add 2 elliptic points
padd :: EC a -> ECPF a -> ECPF a -> ECPF a

-- | add an elliptic point onto itself, base for padd a a
pdouble :: EC a -> ECPF a -> ECPF a

-- | Point Multiplication. The implementation is a montgomery ladder, which
--   should be timing-attack-resistant (except for caches...)
pmul :: EC a -> ECPF a -> FPrime -> ECPF a

-- | "generic" verify, if generic ECP is on EC via getxA and getyA
ison :: EC a -> ECPF a -> Bool
instance GHC.Classes.Eq (Crypto.ECC.NIST.Base.EC a)
instance GHC.Show.Show (Crypto.ECC.NIST.Base.EC a)
instance GHC.Classes.Eq (Crypto.ECC.NIST.Base.ECPF a)
instance GHC.Show.Show (Crypto.ECC.NIST.Base.ECPF a)


-- | basic ECDH functions using hecc
module Crypto.ECC.NIST.ECDH

-- | basic ecdh for testing
basicecdh :: EC Integer -> Integer -> ECPF Integer -> Integer


-- | ECC NIST Standard Curves, taken from
--   NISTReCur.pdf[http:/<i>csrc.nist.gov</i>groups<i>ST</i>toolkit<i>documents</i>dss/NISTReCur.pdf]
--   NB: The rigidity of the curve parameters may be manipulatable, for
--   more information see <a>http://safecurves.cr.yp.to/rigid.html</a>
--   Therein mentioned are only the NIST Prime Curves, because... NB F2:
--   Read up on solving the Discrete Logarithm Problem in fields of small
--   characteristic (i.e. here: Binary Curves) and then decide if the
--   results are relevant to you. Recommendation: If your need NIST Curves
--   and you do not know which one, use the Prime Curves.
module Crypto.ECC.NIST.StandardCurves

-- | Datatype for defined Standard Curves
data StandardCurve
StandardCurve :: Int -> FPrime -> FPrime -> FPrime -> FPrime -> FPrime -> StandardCurve
[stdc_l] :: StandardCurve -> Int
[stdc_p] :: StandardCurve -> FPrime
[stdc_r] :: StandardCurve -> FPrime
[stdc_b] :: StandardCurve -> FPrime
[stdc_xp] :: StandardCurve -> FPrime
[stdc_yp] :: StandardCurve -> FPrime
StandardCurveF2 :: Int -> F2 -> FPrime -> Int -> F2 -> F2 -> F2 -> StandardCurve
[stdcF_l] :: StandardCurve -> Int
[stdcF_p] :: StandardCurve -> F2
[stdcF_r] :: StandardCurve -> FPrime
[stdcF_a] :: StandardCurve -> Int
[stdcF_b] :: StandardCurve -> F2
[stdcF_xp] :: StandardCurve -> F2
[stdcF_yp] :: StandardCurve -> F2

-- | NIST Prime Curve P-192
p192 :: StandardCurve

-- | NIST Prime Curve P-224
p224 :: StandardCurve

-- | NIST Prime Curve P-256
p256 :: StandardCurve

-- | NIST Prime Curve P-384
p384 :: StandardCurve

-- | NIST Prime Curve P-521
p521 :: StandardCurve

-- | NIST Binary Field Curve K-283
k283 :: StandardCurve

-- | NIST Binary Field Curve B-283
b283 :: StandardCurve