-- 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.
@package eccrypto
@version 0.2.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

-- | returning the binary length of an Integer, uses integer-gmp directly
log2len :: Integer -> Int

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


-- | 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, for 1&gt;= k &lt; p
pow :: FPrime -> FPrime -> Integer -> FPrime

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

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

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

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


-- | This module contain the internal functions. It's use should be limited
--   to the ECDH and ECDSA modules, which export certain types without
--   constructors, so the timing attack surface is only over the verified
--   functions. 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]
module Crypto.ECC.Weierstrass.Internal.Curvemath

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

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

-- | internal function, codifies point at infinity, is used in comparisons
isinf :: EC a -> ECPF a -> Bool

-- | 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)

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

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

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

-- | "generic" verify, if generic ECP is on EC via getxA and getyA
ison :: EC a -> ECPF a -> Bool

-- | Point Multiplication.
pmul :: EC a -> ECPF a -> FPrime -> ECPF a
instance GHC.Classes.Eq (Crypto.ECC.Weierstrass.Internal.Curvemath.ECPF a)
instance GHC.Show.Show (Crypto.ECC.Weierstrass.Internal.Curvemath.ECPF a)
instance GHC.Classes.Eq (Crypto.ECC.Weierstrass.Internal.Curvemath.EC a)
instance GHC.Show.Show (Crypto.ECC.Weierstrass.Internal.Curvemath.EC a)


-- | quasi-safe re-exports
module Crypto.ECC.Weierstrass.Internal

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

-- | all Elliptic Curves, the parameters being the BitLength L, A, B and P
data EC a

-- | data of Elliptic Curve Points
data ECPF a

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

-- | 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.
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

-- | internal function, codifies point at infinity, is used in comparisons
isinf :: EC a -> ECPF a -> Bool


-- | 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 you need NIST Curves
--   and you do not know which one, use the Prime Curves.
module Crypto.ECC.Weierstrass.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

-- | 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


-- | basic ECDH, for testing only
module Crypto.ECC.Weierstrass.ECDH

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

-- | all Elliptic Curves, the parameters being the BitLength L, A, B and P
data EC a

-- | data of Elliptic Curve Points
data ECPF a


-- | This module contain the internal functions. It's use should be limited
--   to the Sign module, which exports certain types without constructors,
--   so the timing attack surface is only over the verified functions. In
--   other words: If an external module imports this module or uses
--   unsafecoerce, it may circumvent the verifications against timing
--   attacks!
--   
--   Short-time plan: custom field arithmetic TODO: optimal const time
--   inversion in 25519, see eccss-20130911b.pdf TODO: convert code to
--   portable, get rid of Integer
module Crypto.ECC.Ed25519.Internal.Ed25519

-- | twisted Edwards curve point, extended point format (x,y,z,t), neutral
--   element (0,1,1,0), c=1, a=-1
--   <a>https://hyperelliptic.org/EFD/g1p/auto-twisted-extended-1.html</a>,
--   after "Twisted Edwards curves revisited" eprint 2008/522
newtype Point
Point :: (FPrime, FPrime, FPrime, FPrime) -> Point

-- | clear signal that everything is ok
data SigOK
SigOK :: SigOK

-- | Result of verifying a signature should only yield if it's good or bad,
--   not more, but contains an error string if underlying primitives failed
type VerifyResult = Either String SigOK

-- | just a newtype for the public key (string of 32 bytes, b=256 bit)
type PubKey = ByteString

-- | just a newtype for the public key as a point on the Edwards curve
type PubKeyPoint = Point

-- | just a wrapper for the secret key (string of 32 bytes, b=256 bit)
newtype SecKey
SecKeyBytes :: ByteString -> SecKey

-- | just a wrapper for the secret key as a number
newtype SecFPrime
SecNum :: FPrime -> SecFPrime

-- | just a newtype for the signature (string of 2*32 bytes, b=256 bit)
type Signature = ByteString

-- | just a newtype for the message
type Message = ByteString

-- | just a newtype for the signature with appended message
type SignedMessage = ByteString

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

-- | the large prime
q :: FPrime

-- | curve parameter l, the group order, f.e. needed to use Farmat's little
--   theorem
l :: FPrime

-- | curve parameter d, non-square element, -(121665/121666)
d :: FPrime

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

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

-- | the prehash function, id in PureEdDSA
ph :: ByteString -> ByteString

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

-- | additive neutral element, really (0,Z,Z,0)
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

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

-- | point negation
pneg :: Point -> Point

-- | k=2*d, constant used for point addition
k :: FPrime

-- | point addition add-2008-hwcd-3
padd :: Point -> Point -> Point

-- | point doubling
pdouble :: Point -> Point

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

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

-- | make scalar format Point from projective coordinates
scale :: Point -> Point

-- | 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

-- | clamping of a string of bytes to make it suitable for usage on the
--   (clamped) Edwards curve in Ed25519, reduces cofactor [ b Bits ]
--   001..1000 010..0 BigEndian 01x..x000 ==&gt; ((getFPrime N) .&amp;.
--   (2^254-1-(2^0+2^1+2^2)) .|. (2^254)) .&amp;.
--   28948022309329048855892746252171976963317496166410141009864396001978282409976
--   .|.
--   28948022309329048855892746252171976963317496166410141009864396001978282409984
clamp :: ByteString -> Either String FPrime

-- | convert an 8 Byte little endian ByteString to either an error String
--   (if too short) or a big endian FPrime
convertLE8ByteTo64BE :: ByteString -> Either String FPrime

-- | convert a big endian FPrime to an 8 Byte little endian ByteString
convert64BEtoLE8Byte :: FPrime -> ByteString

-- | converts 32 little endian bytes into one FPrime
getFPrime32 :: ByteString -> Either String FPrime

-- | converts 64 little endian bytes into one FPrime
getFPrime64 :: ByteString -> Either String FPrime

-- | converts one FPrime into exactly 32 little endian bytes
putFPrime :: FPrime -> ByteString
instance GHC.Classes.Eq Crypto.ECC.Ed25519.Internal.Ed25519.SigOK
instance GHC.Show.Show Crypto.ECC.Ed25519.Internal.Ed25519.SigOK
instance GHC.Show.Show Crypto.ECC.Ed25519.Internal.Ed25519.Point
instance GHC.Classes.Eq Crypto.ECC.Ed25519.Internal.Ed25519.Point


-- | Short-time plan: custom field arithmetic TODO: optimal const time
--   inversion in 25519, see eccss-20130911b.pdf TODO: convert code to
--   portable implementation and get rid of Integer
module Crypto.ECC.Ed25519.Sign

-- | generate a new key pair (secret and derived public key) using some
--   external entropy | This may be insecure, depending on your
--   environment, so for your usage case you may need to implement some
--   better key generator!
genkeys :: IO (Either String (SecKey, PubKey))

-- | derive public key from secret key
publickey :: SecKey -> Either String PubKey

-- | sign the message m with secret key sk, resulting in a detached
--   signature
dsign :: SecKey -> Message -> Either String Signature

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

-- | in: public key, message and signature, out: is the signature valid for
--   public key and message?
dverify :: PubKey -> Signature -> Message -> VerifyResult

-- | wrapper around dverify, in case we work with a signed message, i.e.
--   the signature with appended message
verify :: PubKey -> SignedMessage -> VerifyResult

-- | just a newtype for the message
type Message = ByteString

-- | just a newtype for the public key (string of 32 bytes, b=256 bit)
type PubKey = ByteString

-- | just a wrapper for the secret key (string of 32 bytes, b=256 bit)
data SecKey

-- | just a newtype for the signature (string of 2*32 bytes, b=256 bit)
type Signature = ByteString

-- | just a newtype for the signature with appended message
type SignedMessage = ByteString

-- | clear signal that everything is ok
data SigOK
SigOK :: SigOK

-- | Result of verifying a signature should only yield if it's good or bad,
--   not more, but contains an error string if underlying primitives failed
type VerifyResult = Either String SigOK


-- | safe re-exports
module Crypto.ECC.Ed25519.Internal

-- | twisted Edwards curve point, extended point format (x,y,z,t), neutral
--   element (0,1,1,0), c=1, a=-1
--   <a>https://hyperelliptic.org/EFD/g1p/auto-twisted-extended-1.html</a>,
--   after "Twisted Edwards curves revisited" eprint 2008/522
data Point

-- | just a newtype for the message
type Message = ByteString

-- | just a newtype for the public key (string of 32 bytes, b=256 bit)
type PubKey = ByteString

-- | just a wrapper for the secret key (string of 32 bytes, b=256 bit)
data SecKey

-- | just a newtype for the signature (string of 2*32 bytes, b=256 bit)
type Signature = ByteString

-- | just a newtype for the signature with appended message
type SignedMessage = ByteString

-- | clear signal that everything is ok
data SigOK
SigOK :: SigOK

-- | Result of verifying a signature should only yield if it's good or bad,
--   not more, but contains an error string if underlying primitives failed
type VerifyResult = Either String SigOK

-- | converts 32 little endian bytes into one FPrime
getFPrime32 :: ByteString -> Either String FPrime


-- | basic ECDSA, probably insecure if used improperly (really needs random
--   k), for testing only
module Crypto.ECC.Weierstrass.ECDSA

-- | basic ecdsa for testing
basicecdsa :: ByteString -> Integer -> Integer -> Either String (Integer, Integer)

-- | basic ECDSA verification
basicecdsaVerify :: ECPF Integer -> (Integer, Integer) -> ByteString -> Bool

-- | data of Elliptic Curve Points
data ECPF a