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


-- | Public Key cryptography
--   
--   Public Key cryptography
--   
--   Supports RSA PKCS15, RSA OAEP, RSA PSS, DSA, ElGamal signature.
--   
--   Also have primitive support for Diffie Hellman, and ElGamal encryption
@package crypto-pubkey
@version 0.2.4


-- | Elliptic Curve Arithmetic.
--   
--   <i>WARNING:</i> These functions are vulnerable to timing attacks.
module Crypto.PubKey.ECC.Prim

-- | Elliptic Curve point addition.
--   
--   <i>WARNING:</i> Vulnerable to timing attacks.
pointAdd :: Curve -> Point -> Point -> Point

-- | Elliptic Curve point doubling.
--   
--   <i>WARNING:</i> Vulnerable to timing attacks.
pointDouble :: Curve -> Point -> Point

-- | Elliptic curve point multiplication (double and add algorithm).
--   
--   <i>WARNING:</i> Vulnerable to timing attacks.
pointMul :: Curve -> Integer -> Point -> Point


-- | Signature generation.
module Crypto.PubKey.ECC.Generate

-- | Generate Q given d.
--   
--   <i>WARNING:</i> Vulnerable to timing attacks.
generateQ :: Curve -> Integer -> Point

-- | Generate a pair of (private, public) key.
--   
--   <i>WARNING:</i> Vulnerable to timing attacks.
generate :: CPRG g => g -> Curve -> ((PublicKey, PrivateKey), g)


module Crypto.PubKey.DH

-- | Represent Diffie Hellman parameters namely P (prime), and G
--   (generator).
data Params :: *
Params :: Integer -> Integer -> Params
params_p :: Params -> Integer
params_g :: Params -> Integer

-- | Represent Diffie Hellman public number Y.
data PublicNumber :: *

-- | Represent Diffie Hellman private number X.
data PrivateNumber :: *

-- | Represent Diffie Hellman shared secret.
data SharedKey :: *

-- | generate params from a specific generator (2 or 5 are common values)
--   we generate a safe prime (a prime number of the form 2p+1 where p is
--   also prime)
generateParams :: CPRG g => g -> Int -> Integer -> (Params, g)

-- | generate a private number with no specific property this number is
--   usually called X in DH text.
generatePrivate :: CPRG g => g -> Params -> (PrivateNumber, g)

-- | calculate the public number from the parameters and the private key
--   this number is usually called Y in DH text.
calculatePublic :: Params -> PrivateNumber -> PublicNumber

-- | calculate the public number from the parameters and the private key
--   this number is usually called Y in DH text.
--   
--   DEPRECATED use calculatePublic
generatePublic :: Params -> PrivateNumber -> PublicNumber

-- | generate a shared key using our private number and the other party
--   public number
getShared :: Params -> PrivateNumber -> PublicNumber -> SharedKey


-- | Standard digests wrapped in ASN1 structure
module Crypto.PubKey.HashDescr

-- | A standard hash function returning a digest object
type HashFunction = ByteString -> ByteString

-- | Describe a hash function and a way to wrap the digest into an DER
--   encoded ASN1 marshalled structure.
data HashDescr
HashDescr :: HashFunction -> (ByteString -> ByteString) -> HashDescr

-- | hash function
hashFunction :: HashDescr -> HashFunction

-- | convertion to an ASN1 wrapped digest bytestring
digestToASN1 :: HashDescr -> ByteString -> ByteString

-- | Describe the MD2 hashing algorithm
hashDescrMD2 :: HashDescr

-- | Describe the MD5 hashing algorithm
hashDescrMD5 :: HashDescr

-- | Describe the SHA1 hashing algorithm
hashDescrSHA1 :: HashDescr

-- | Describe the SHA224 hashing algorithm
hashDescrSHA224 :: HashDescr

-- | Describe the SHA256 hashing algorithm
hashDescrSHA256 :: HashDescr

-- | Describe the SHA384 hashing algorithm
hashDescrSHA384 :: HashDescr

-- | Describe the SHA512 hashing algorithm
hashDescrSHA512 :: HashDescr

-- | Describe the RIPEMD160 hashing algorithm
hashDescrRIPEMD160 :: HashDescr


module Crypto.PubKey.MaskGenFunction

-- | Represent a mask generation algorithm
type MaskGenAlgorithm = HashFunction -> ByteString -> Int -> ByteString

-- | Mask generation algorithm MGF1
mgf1 :: MaskGenAlgorithm


-- | An implementation of the Digital Signature Algorithm (DSA)
module Crypto.PubKey.DSA

-- | Represent DSA parameters namely P, G, and Q.
data Params :: *
Params :: Integer -> Integer -> Integer -> Params

-- | DSA p
params_p :: Params -> Integer

-- | DSA g
params_g :: Params -> Integer

-- | DSA q
params_q :: Params -> Integer

-- | Represent a DSA signature namely R and S.
data Signature :: *
Signature :: Integer -> Integer -> Signature

-- | DSA r
sign_r :: Signature -> Integer

-- | DSA s
sign_s :: Signature -> Integer

-- | Represent a DSA public key.
data PublicKey :: *
PublicKey :: Params -> PublicNumber -> PublicKey

-- | DSA parameters
public_params :: PublicKey -> Params

-- | DSA public Y
public_y :: PublicKey -> PublicNumber

-- | Represent a DSA private key.
--   
--   Only x need to be secret. the DSA parameters are publicly shared with
--   the other side.
data PrivateKey :: *
PrivateKey :: Params -> PrivateNumber -> PrivateKey

-- | DSA parameters
private_params :: PrivateKey -> Params

-- | DSA private X
private_x :: PrivateKey -> PrivateNumber

-- | generate a private number with no specific property this number is
--   usually called X in DSA text.
generatePrivate :: CPRG g => g -> Params -> (PrivateNumber, g)

-- | Calculate the public number from the parameters and the private key
calculatePublic :: Params -> PrivateNumber -> PublicNumber

-- | sign message using the private key.
sign :: CPRG g => g -> PrivateKey -> HashFunction -> ByteString -> (Signature, g)

-- | sign message using the private key and an explicit k number.
signWith :: Integer -> PrivateKey -> HashFunction -> ByteString -> Maybe Signature

-- | verify a bytestring using the public key.
verify :: HashFunction -> PublicKey -> Signature -> ByteString -> Bool


-- | <i>WARNING:</i> Signature operations may leak the private key.
--   Signature verification should be safe.
module Crypto.PubKey.ECC.ECDSA

-- | Sign message using the private key and an explicit k number.
--   
--   <i>WARNING:</i> Vulnerable to timing attacks.
signWith :: Integer -> PrivateKey -> HashFunction -> ByteString -> Maybe Signature

-- | Sign message using the private key.
--   
--   <i>WARNING:</i> Vulnerable to timing attacks.
sign :: CPRG g => g -> PrivateKey -> HashFunction -> ByteString -> (Signature, g)

-- | Verify a bytestring using the public key.
verify :: HashFunction -> PublicKey -> Signature -> ByteString -> Bool


module Crypto.PubKey.RSA.Prim

-- | Compute the RSA decrypt primitive. if the p and q numbers are
--   available, then dpFast is used otherwise, we use dpSlow which only
--   need d and n.
dp :: Maybe Blinder -> PrivateKey -> ByteString -> ByteString

-- | Compute the RSA encrypt primitive
ep :: PublicKey -> ByteString -> ByteString


module Crypto.PubKey.RSA

-- | error possible during encryption, decryption or signing.
data Error

-- | the message to decrypt is not of the correct size (need to be ==
--   private_size)
MessageSizeIncorrect :: Error

-- | the message to encrypt is too long
MessageTooLong :: Error

-- | the message decrypted doesn't have a PKCS15 structure (0 2 .. 0 msg)
MessageNotRecognized :: Error

-- | the message's digest is too long
SignatureTooLong :: Error

-- | some parameters lead to breaking assumptions.
InvalidParameters :: Error

-- | Represent a RSA public key
data PublicKey :: *
PublicKey :: Int -> Integer -> Integer -> PublicKey

-- | size of key in bytes
public_size :: PublicKey -> Int

-- | public p*q
public_n :: PublicKey -> Integer

-- | public exponant e
public_e :: PublicKey -> Integer

-- | Represent a RSA private key.
--   
--   Only the pub, d fields are mandatory to fill.
--   
--   p, q, dP, dQ, qinv are by-product during RSA generation, but are
--   useful to record here to speed up massively the decrypt and sign
--   operation.
--   
--   implementations can leave optional fields to 0.
data PrivateKey :: *
PrivateKey :: PublicKey -> Integer -> Integer -> Integer -> Integer -> Integer -> Integer -> PrivateKey

-- | public part of a private key (size, n and e)
private_pub :: PrivateKey -> PublicKey

-- | private exponant d
private_d :: PrivateKey -> Integer

-- | p prime number
private_p :: PrivateKey -> Integer

-- | q prime number
private_q :: PrivateKey -> Integer

-- | d mod (p-1)
private_dP :: PrivateKey -> Integer

-- | d mod (q-1)
private_dQ :: PrivateKey -> Integer

-- | q^(-1) mod p
private_qinv :: PrivateKey -> Integer

-- | Blinder which is used to obfuscate the timing of the decryption
--   primitive (used by decryption and signing).
data Blinder
Blinder :: !Integer -> !Integer -> Blinder

-- | Generate a key pair given p and q.
--   
--   p and q need to be distinct prime numbers.
--   
--   e need to be coprime to phi=(p-1)*(q-1). If that's not the case, the
--   function will not return a key pair. A small hamming weight results in
--   better performance.
--   
--   <ul>
--   <li>e=0x10001 is a popular choice</li>
--   <li>e=3 is popular as well, but proven to not be as secure for some
--   cases.</li>
--   </ul>
generateWith :: (Integer, Integer) -> Int -> Integer -> Maybe (PublicKey, PrivateKey)

-- | generate a pair of (private, public) key of size in bytes.
generate :: CPRG g => g -> Int -> Integer -> ((PublicKey, PrivateKey), g)

-- | Generate a blinder to use with decryption and signing operation
--   
--   the unique parameter apart from the random number generator is the
--   public key value N.
generateBlinder :: CPRG g => g -> Integer -> (Blinder, g)


module Crypto.PubKey.RSA.PKCS15

-- | This produce a standard PKCS1.5 padding for encryption
pad :: CPRG g => g -> Int -> ByteString -> Either Error (ByteString, g)

-- | Produce a standard PKCS1.5 padding for signature
padSignature :: Int -> ByteString -> Either Error ByteString

-- | Try to remove a standard PKCS1.5 encryption padding.
unpad :: ByteString -> Either Error ByteString

-- | decrypt message using the private key.
--   
--   When the decryption is not in a context where an attacker could gain
--   information from the timing of the operation, the blinder can be set
--   to None.
--   
--   If unsure always set a blinder or use decryptSafer
decrypt :: Maybe Blinder -> PrivateKey -> ByteString -> Either Error ByteString

-- | decrypt message using the private key and by automatically generating
--   a blinder.
decryptSafer :: CPRG g => g -> PrivateKey -> ByteString -> (Either Error ByteString, g)

-- | sign message using private key, a hash and its ASN1 description
--   
--   When the signature is not in a context where an attacker could gain
--   information from the timing of the operation, the blinder can be set
--   to None.
--   
--   If unsure always set a blinder or use signSafer
sign :: Maybe Blinder -> HashDescr -> PrivateKey -> ByteString -> Either Error ByteString

-- | sign message using the private key and by automatically generating a
--   blinder.
signSafer :: CPRG g => g -> HashDescr -> PrivateKey -> ByteString -> (Either Error ByteString, g)

-- | encrypt a bytestring using the public key and a CPRG random generator.
--   
--   the message need to be smaller than the key size - 11
encrypt :: CPRG g => g -> PublicKey -> ByteString -> (Either Error ByteString, g)

-- | verify message with the signed message
verify :: HashDescr -> PublicKey -> ByteString -> ByteString -> Bool


-- | RSA OAEP mode
--   <a>http://en.wikipedia.org/wiki/Optimal_asymmetric_encryption_padding</a>
module Crypto.PubKey.RSA.OAEP

-- | Parameters for OAEP encryption/decryption
data OAEPParams
OAEPParams :: HashFunction -> MaskGenAlgorithm -> Maybe ByteString -> OAEPParams

-- | Hash function to use.
oaepHash :: OAEPParams -> HashFunction

-- | Mask Gen algorithm to use.
oaepMaskGenAlg :: OAEPParams -> MaskGenAlgorithm

-- | Optional label prepended to message.
oaepLabel :: OAEPParams -> Maybe ByteString

-- | Default Params with a specified hash function
defaultOAEPParams :: HashFunction -> OAEPParams

-- | Encrypt a message using OAEP with a predefined seed.
encryptWithSeed :: ByteString -> OAEPParams -> PublicKey -> ByteString -> Either Error ByteString

-- | Encrypt a message using OAEP
encrypt :: CPRG g => g -> OAEPParams -> PublicKey -> ByteString -> (Either Error ByteString, g)

-- | Decrypt a ciphertext using OAEP
--   
--   When the signature is not in a context where an attacker could gain
--   information from the timing of the operation, the blinder can be set
--   to None.
--   
--   If unsure always set a blinder or use decryptSafer
decrypt :: Maybe Blinder -> OAEPParams -> PrivateKey -> ByteString -> Either Error ByteString

-- | Decrypt a ciphertext using OAEP and by automatically generating a
--   blinder.
decryptSafer :: CPRG g => g -> OAEPParams -> PrivateKey -> ByteString -> (Either Error ByteString, g)


module Crypto.PubKey.RSA.PSS

-- | Parameters for PSS signature/verification.
data PSSParams
PSSParams :: HashFunction -> MaskGenAlgorithm -> Int -> Word8 -> PSSParams

-- | Hash function to use
pssHash :: PSSParams -> HashFunction

-- | Mask Gen algorithm to use
pssMaskGenAlg :: PSSParams -> MaskGenAlgorithm

-- | Length of salt. need to be &lt;= to hLen.
pssSaltLength :: PSSParams -> Int

-- | Trailer field, usually 0xbc
pssTrailerField :: PSSParams -> Word8

-- | Default Params with a specified hash function
defaultPSSParams :: HashFunction -> PSSParams

-- | Default Params using SHA1 algorithm.
defaultPSSParamsSHA1 :: PSSParams

-- | Sign using the PSS parameters and the salt explicitely passed as
--   parameters.
--   
--   the function ignore SaltLength from the PSS Parameters
signWithSalt :: ByteString -> Maybe Blinder -> PSSParams -> PrivateKey -> ByteString -> Either Error ByteString

-- | Sign using the PSS Parameters
sign :: CPRG g => g -> Maybe Blinder -> PSSParams -> PrivateKey -> ByteString -> (Either Error ByteString, g)

-- | Sign using the PSS Parameters and an automatically generated blinder.
signSafer :: CPRG g => g -> PSSParams -> PrivateKey -> ByteString -> (Either Error ByteString, g)

-- | Verify a signature using the PSS Parameters
verify :: PSSParams -> PublicKey -> ByteString -> ByteString -> Bool
