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


-- | Implementation of DSA, based on the description of FIPS 186-4
--   
--   This library implements the DSA encryption and signature algorithms
--   for arbitrarily-sized ByteStrings. While the implementations work,
--   they are not necessarily the fastest ones on the planet. Particularly
--   key generation. The algorithms included are based of NIST's FIPS 186-4
--   document.
@package DSA
@version 1

module Codec.Crypto.DSA.Pure
data ParameterSizes
L1024_N160 :: ParameterSizes
L2048_N224 :: ParameterSizes
L2048_N256 :: ParameterSizes
L3072_N256 :: ParameterSizes

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

-- | 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
data DSAError
DSARandomGenerationError :: GenError -> DSAError
DSAInvalidSeedLength :: DSAError
DSAInvalidPrimeTestInput :: DSAError
DSAInvalidInput :: DSAError
DSAInternalInversionError :: DSAError
DSAGaveUp :: DSAError

-- | Get the N parameter, in bits.
getN :: ParameterSizes -> Integer

-- | Get the L parameter, in bits.
getL :: ParameterSizes -> Integer

-- | Generate a DSA key pair. This will also generate the <i>p</i>,
--   <i>q</i>, and <i>g</i> parameters using provable and verifiable
--   algorithms, with SHA-256 as the hash function. If you want to use your
--   own <i>p</i>, <i>q</i>, and <i>g</i> values or specify your own
--   generation or hash function,, use the <a>generateKeyPairWithParams</a>
--   function, below.
generateKeyPair :: CryptoRandomGen g => g -> ParameterSizes -> Either DSAError (PublicKey, PrivateKey, ProvablePrimesEvidence, g)

-- | Generate a key pair given a set of DSA parameters. You really should
--   have validated this set (<i>p</i>, <i>q</i>, and <i>g</i>) using the
--   relevant functions below before you do this. Doing so even if you
--   generated them is probably not a bad practice.
--   
--   This uses the method using extra random bits from FIPS 186-4. You
--   better be using a good enough random number generator.
generateKeyPairWithParams :: CryptoRandomGen g => Params -> g -> Either DSAError (PublicKey, PrivateKey, g)

-- | Sign a message using DSA. This method utilizes very good defaults for
--   message signing that should be acceptable for most use cases: it uses
--   SHA-256 for the hash function, and generates <i>k</i> using the
--   methods described in RFC 6979. If you wish to change these defaults,
--   please see <tt>signMessaage'</tt>.
signMessage :: PrivateKey -> ByteString -> Either DSAError Signature

-- | Verify a DSA message signature. This uses the same default mechanisms
--   as <a>signMessage</a>.
verifyMessage :: PublicKey -> ByteString -> Signature -> Bool

-- | The hash to use in generating the signature. We strongly recommend
--   SHA256 or better.
data HashFunction
SHA1 :: HashFunction
SHA224 :: HashFunction
SHA256 :: HashFunction
SHA384 :: HashFunction
SHA512 :: HashFunction

-- | Sign a message given the hash function an <i>k</i> generation routine.
--   Returns either an error the signature generated. You can define your
--   own <i>k</i> generation routine ... but we don't recommend it.
--   Actually, while we're recommending, we recommend you use
--   <a>kViaRFC6979</a>, if you're not sure which to use.
signMessage' :: CryptoRandomGen g => HashFunction -> KGenerator g -> g -> PrivateKey -> ByteString -> Either DSAError (Signature, g)

-- | Verify a signed message. You need to know what hash algorithm they
--   used to generate the signature, and pass it in. Returns True if the
--   signature was valid.
verifyMessage' :: HashFunction -> PublicKey -> ByteString -> Signature -> Bool
type KGenerator g = g -> HashFunction -> PrivateKey -> ByteString -> KSequence g
data CryptoRandomGen g => KSequence g
KValue :: Integer -> g -> (KSequence g) -> KSequence g
KFailure :: DSAError -> KSequence g
kViaExtraRandomBits :: CryptoRandomGen g => KGenerator g
kViaTestingCandidates :: CryptoRandomGen g => KGenerator g
kViaRFC6979 :: CryptoRandomGen g => KGenerator g

-- | The evidence generated when generating probably primes. This evidence
--   can be used to ensure that the <i>p</i> and <i>q</i> values provided
--   were generated appropriately.
data ProbablePrimesEvidence
ProbablePrimesEvidence :: Integer -> Integer -> (ByteString -> ByteString) -> ProbablePrimesEvidence
[prpeDomainParameterSeed] :: ProbablePrimesEvidence -> Integer
[prpeCounter] :: ProbablePrimesEvidence -> Integer
[prpeHash] :: ProbablePrimesEvidence -> ByteString -> ByteString

-- | Using an approved hash function -- at the point of writing, a SHA-2
--   variant -- generate values of p and q for use in DSA, for which p and
--   q have a very high probability of being prime. In addition to p and q,
--   this routine returns the "domain parameter seed" and "counter" used to
--   generate the primes. These can be supplied to later validation
--   functions; their secrecy is not required for the algorithm to work.
--   
--   The inputs to the function are the DSA parameters we are generating a
--   key for, a source of entropy, the hash function to use, and
--   (optionally) the length of the domain parameter seed to use. The last
--   item must be greater to or later to the value of n, if supplied, and
--   will be set to (n + 8) if not.
--   
--   The security of this method depends on the strength of the hash being
--   used. To that end, FIPS 140-2 requires a SHA-2 variant.
generateProbablePrimes :: CryptoRandomGen g => ParameterSizes -> g -> (ByteString -> ByteString) -> Maybe Integer -> Either DSAError (Integer, Integer, ProbablePrimesEvidence, g)

-- | Validate that the probable primes that either you generated or that
--   someone provided to you are legitimate.
validateProbablePrimes :: CryptoRandomGen g => g -> Integer -> Integer -> ProbablePrimesEvidence -> (Bool, g)
data ProvablePrimesEvidence
ProvablePrimesEvidence :: Integer -> Integer -> Integer -> Integer -> Integer -> (ByteString -> ByteString) -> ProvablePrimesEvidence
[pvpeFirstSeed] :: ProvablePrimesEvidence -> Integer
[pvpePSeed] :: ProvablePrimesEvidence -> Integer
[pvpeQSeed] :: ProvablePrimesEvidence -> Integer
[pvpePGenCounter] :: ProvablePrimesEvidence -> Integer
[pvpeQGenCounter] :: ProvablePrimesEvidence -> Integer
[pvpeHash] :: ProvablePrimesEvidence -> ByteString -> ByteString

-- | Using an approved hash function -- at the point of writing, a SHA-2
--   variant -- generate values of p and q for use in DSA, for which p and
--   q are provably prime. In addition to p and q, this routine generates a
--   series of additional values that can be used to validate that this
--   algorithm performed correctly.
--   
--   The inputs to the function are the DSA parameters we are generating
--   key for, a source of entropy, the hash function to use, and
--   (optionally) an initial seed length in bits. The last item, if
--   provided, must be greater than or equal to the N value being tested
--   against, and must be a multiple of 8.
generateProvablePrimes :: CryptoRandomGen g => ParameterSizes -> g -> (ByteString -> ByteString) -> Maybe Integer -> Either DSAError (Integer, Integer, ProvablePrimesEvidence, g)

-- | Validate that the provable primes that either you generated or that
--   someone provided to you are legitimate.
validateProvablePrimes :: Integer -> Integer -> ProvablePrimesEvidence -> Bool
class GenerationEvidence a

-- | Generate the generator <i>g</i> using a method that is not verifiable
--   to a third party. Quoth FIPS: "[This] method ... may be used when
--   complete validation of the generator <i>g</i> is not required; it is
--   recommended that this method be used only when the party generating
--   <i>g</i> is trusted to not deliberately generate a <i>g</i> that has a
--   potentially exploitable relationship to another generator <i>g'</i>.
--   
--   The input to this function are a valid <i>p</i> and <i>q</i>,
--   generated using an approved method.
--   
--   It may be possible (?) that this routine could fail to find a possible
--   generator. In that case, Nothing is returned.
generateUnverifiableGenerator :: Integer -> Integer -> Maybe Integer

-- | Validate that the given generator <i>g</i> works for the values
--   <i>p</i> and <i>q</i> provided.
generatorIsValid :: Integer -> Integer -> Integer -> Bool

-- | Generate a generator <i>g</i>, given the values of <i>p</i>, <i>q</i>,
--   the evidence created generating those values, and an index. Quoth
--   FIPS: "This generation method supports the generation of multiple
--   values of <i>g</i> for specific values of <i>p</i> and <i>q</i>. The
--   use of different values of <i>g</i> for the same <i>p</i> and <i>q</i>
--   may be used to support key separation; for example, using the <i>g</i>
--   that is generated with <tt>index = 1</tt> for digital signatures and
--   with <tt>index = 2</tt> for key establishment."
--   
--   This method is replicatable, so that given the same inputs it will
--   generate the same outputs. Thus, you can validate that the <i>g</i>
--   generated using this method was generated correctly using
--   <a>validateVerifiableGenerator</a>, which will be nice if you don't
--   trust the person you're talking to.
generateVerifiableGenerator :: GenerationEvidence ev => Integer -> Integer -> ev -> Word8 -> Maybe Integer

-- | Validate that the value <i>g</i> was generated by
--   <a>generateVerifiableGenerator</a> or someone using the same
--   algorithm. This is probably a good idea if you don't trust your
--   compatriot.
validateVerifiableGenerator :: GenerationEvidence ev => Integer -> Integer -> ev -> Word8 -> Integer -> Bool

-- | Perform the given number of iterations of the Miller-Rabin test to try
--   to determine if the given Integer is prime.
millerRabin :: CryptoRandomGen g => g -> Int -> Integer -> Either DSAError (Bool, g)

-- | A brute force check to determine if a number is prime. This answer is
--   guaranteed to be correct, but should only be used on small numbers
--   (less than 33 bits would be nice).
isDeterministicallyPrime :: Integer -> Bool
shaweTaylor :: (ByteString -> ByteString) -> Integer -> Integer -> Either DSAError (Integer, Integer, Integer)

-- | Convert a ByteString into its obvious Integer representation.
bs2int :: ByteString -> Integer
bss2int :: ByteString -> Integer

-- | Convert an Integer into its obvious ByteString representation.
int2bs :: Integer -> ByteString

-- | Find <tt>a</tt> and <tt>m</tt> such that input = 2^a * m.
findAandM :: Integer -> (Integer, Integer)
modExp :: Integer -> Integer -> Integer -> Integer
instance GHC.Show.Show Codec.Crypto.DSA.Pure.HashFunction
instance GHC.Classes.Eq Codec.Crypto.DSA.Pure.HashFunction
instance GHC.Show.Show Codec.Crypto.DSA.Pure.DSAError
instance GHC.Classes.Eq Codec.Crypto.DSA.Pure.DSAError
instance GHC.Show.Show Codec.Crypto.DSA.Pure.ParameterSizes
instance GHC.Classes.Eq Codec.Crypto.DSA.Pure.ParameterSizes
instance GHC.Exception.Exception Codec.Crypto.DSA.Pure.DSAError
instance GHC.Classes.Eq Codec.Crypto.DSA.Pure.ProvablePrimesEvidence
instance Codec.Crypto.DSA.Pure.GenerationEvidence Codec.Crypto.DSA.Pure.ProbablePrimesEvidence
instance Codec.Crypto.DSA.Pure.GenerationEvidence Codec.Crypto.DSA.Pure.ProvablePrimesEvidence
instance Crypto.Random.CryptoRandomGen Codec.Crypto.DSA.Pure.NoGen

module Codec.Crypto.DSA.Exceptions
data ParameterSizes
L1024_N160 :: ParameterSizes
L2048_N224 :: ParameterSizes
L2048_N256 :: ParameterSizes
L3072_N256 :: ParameterSizes

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

-- | 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
data DSAError
DSARandomGenerationError :: GenError -> DSAError
DSAInvalidSeedLength :: DSAError
DSAInvalidPrimeTestInput :: DSAError
DSAInvalidInput :: DSAError
DSAInternalInversionError :: DSAError
DSAGaveUp :: DSAError

-- | Get the N parameter, in bits.
getN :: ParameterSizes -> Integer

-- | Get the L parameter, in bits.
getL :: ParameterSizes -> Integer

-- | Generate a DSA key pair. This will also generate the <i>p</i>,
--   <i>q</i>, and <i>g</i> parameters using provable and verifiable
--   algorithms, with SHA-256 as the hash function. If you want to use your
--   own <i>p</i>, <i>q</i>, and <i>g</i> values or specify your own
--   generation or hash function,, use the <a>generateKeyPairWithParams</a>
--   function, below.
generateKeyPair :: CryptoRandomGen g => g -> ParameterSizes -> (PublicKey, PrivateKey, ProvablePrimesEvidence, g)

-- | Generate a key pair given a set of DSA parameters. You really should
--   have validated this set (<i>p</i>, <i>q</i>, and <i>g</i>) using the
--   relevant functions below before you do this. Doing so even if you
--   generated them is probably not a bad practice.
--   
--   This uses the method using extra random bits from FIPS 186-4. You
--   better be using a good enough random number generator.
generateKeyPairWithParams :: CryptoRandomGen g => Params -> g -> (PublicKey, PrivateKey, g)

-- | Sign a message using DSA. This method utilizes very good defaults for
--   message signing that should be acceptable for most use cases: it uses
--   SHA-256 for the hash function, and generates <i>k</i> using the
--   methods described in RFC 6979. If you wish to change these defaults,
--   please see <tt>signMessaage'</tt>.
signMessage :: PrivateKey -> ByteString -> Signature

-- | Verify a DSA message signature. This uses the same default mechanisms
--   as <a>signMessage</a>.
verifyMessage :: PublicKey -> ByteString -> Signature -> Bool

-- | The hash to use in generating the signature. We strongly recommend
--   SHA256 or better.
data HashFunction
SHA1 :: HashFunction
SHA224 :: HashFunction
SHA256 :: HashFunction
SHA384 :: HashFunction
SHA512 :: HashFunction

-- | Sign a message given the hash function an <i>k</i> generation routine.
--   Returns either an error the signature generated. You can define your
--   own <i>k</i> generation routine ... but we don't recommend it.
--   Actually, while we're recommending, we recommend you use
--   <a>kViaRFC6979</a>, if you're not sure which to use.
signMessage' :: CryptoRandomGen g => HashFunction -> KGenerator g -> g -> PrivateKey -> ByteString -> (Signature, g)

-- | Verify a signed message. You need to know what hash algorithm they
--   used to generate the signature, and pass it in. Returns True if the
--   signature was valid.
verifyMessage' :: HashFunction -> PublicKey -> ByteString -> Signature -> Bool
type KGenerator g = g -> HashFunction -> PrivateKey -> ByteString -> KSequence g
data CryptoRandomGen g => KSequence g
KValue :: Integer -> g -> (KSequence g) -> KSequence g
KFailure :: DSAError -> KSequence g
kViaExtraRandomBits :: CryptoRandomGen g => KGenerator g
kViaTestingCandidates :: CryptoRandomGen g => KGenerator g
kViaRFC6979 :: CryptoRandomGen g => KGenerator g

-- | The evidence generated when generating probably primes. This evidence
--   can be used to ensure that the <i>p</i> and <i>q</i> values provided
--   were generated appropriately.
data ProbablePrimesEvidence
ProbablePrimesEvidence :: Integer -> Integer -> (ByteString -> ByteString) -> ProbablePrimesEvidence
[prpeDomainParameterSeed] :: ProbablePrimesEvidence -> Integer
[prpeCounter] :: ProbablePrimesEvidence -> Integer
[prpeHash] :: ProbablePrimesEvidence -> ByteString -> ByteString

-- | Using an approved hash function -- at the point of writing, a SHA-2
--   variant -- generate values of p and q for use in DSA, for which p and
--   q have a very high probability of being prime. In addition to p and q,
--   this routine returns the "domain parameter seed" and "counter" used to
--   generate the primes. These can be supplied to later validation
--   functions; their secrecy is not required for the algorithm to work.
--   
--   The inputs to the function are the DSA parameters we are generating a
--   key for, a source of entropy, the hash function to use, and
--   (optionally) the length of the domain parameter seed to use. The last
--   item must be greater to or later to the value of n, if supplied, and
--   will be set to (n + 8) if not.
--   
--   The security of this method depends on the strength of the hash being
--   used. To that end, FIPS 140-2 requires a SHA-2 variant.
generateProbablePrimes :: CryptoRandomGen g => ParameterSizes -> g -> (ByteString -> ByteString) -> Maybe Integer -> (Integer, Integer, ProbablePrimesEvidence, g)

-- | Validate that the probable primes that either you generated or that
--   someone provided to you are legitimate.
validateProbablePrimes :: CryptoRandomGen g => g -> Integer -> Integer -> ProbablePrimesEvidence -> (Bool, g)
data ProvablePrimesEvidence
ProvablePrimesEvidence :: Integer -> Integer -> Integer -> Integer -> Integer -> (ByteString -> ByteString) -> ProvablePrimesEvidence
[pvpeFirstSeed] :: ProvablePrimesEvidence -> Integer
[pvpePSeed] :: ProvablePrimesEvidence -> Integer
[pvpeQSeed] :: ProvablePrimesEvidence -> Integer
[pvpePGenCounter] :: ProvablePrimesEvidence -> Integer
[pvpeQGenCounter] :: ProvablePrimesEvidence -> Integer
[pvpeHash] :: ProvablePrimesEvidence -> ByteString -> ByteString

-- | Using an approved hash function -- at the point of writing, a SHA-2
--   variant -- generate values of p and q for use in DSA, for which p and
--   q are provably prime. In addition to p and q, this routine generates a
--   series of additional values that can be used to validate that this
--   algorithm performed correctly.
--   
--   The inputs to the function are the DSA parameters we are generating
--   key for, a source of entropy, the hash function to use, and
--   (optionally) an initial seed length in bits. The last item, if
--   provided, must be greater than or equal to the N value being tested
--   against, and must be a multiple of 8.
generateProvablePrimes :: CryptoRandomGen g => ParameterSizes -> g -> (ByteString -> ByteString) -> Maybe Integer -> (Integer, Integer, ProvablePrimesEvidence, g)

-- | Validate that the provable primes that either you generated or that
--   someone provided to you are legitimate.
validateProvablePrimes :: Integer -> Integer -> ProvablePrimesEvidence -> Bool

-- | Generate the generator <i>g</i> using a method that is not verifiable
--   to a third party. Quoth FIPS: "[This] method ... may be used when
--   complete validation of the generator <i>g</i> is not required; it is
--   recommended that this method be used only when the party generating
--   <i>g</i> is trusted to not deliberately generate a <i>g</i> that has a
--   potentially exploitable relationship to another generator <i>g'</i>.
--   
--   The input to this function are a valid <i>p</i> and <i>q</i>,
--   generated using an approved method.
--   
--   It may be possible (?) that this routine could fail to find a possible
--   generator. In that case, Nothing is returned.
generateUnverifiableGenerator :: Integer -> Integer -> Integer

-- | Validate that the given generator <i>g</i> works for the values
--   <i>p</i> and <i>q</i> provided.
generatorIsValid :: Integer -> Integer -> Integer -> Bool

-- | Generate a generator <i>g</i>, given the values of <i>p</i>, <i>q</i>,
--   the evidence created generating those values, and an index. Quoth
--   FIPS: "This generation method supports the generation of multiple
--   values of <i>g</i> for specific values of <i>p</i> and <i>q</i>. The
--   use of different values of <i>g</i> for the same <i>p</i> and <i>q</i>
--   may be used to support key separation; for example, using the <i>g</i>
--   that is generated with <tt>index = 1</tt> for digital signatures and
--   with <tt>index = 2</tt> for key establishment."
--   
--   This method is replicatable, so that given the same inputs it will
--   generate the same outputs. Thus, you can validate that the <i>g</i>
--   generated using this method was generated correctly using
--   <a>validateVerifiableGenerator</a>, which will be nice if you don't
--   trust the person you're talking to.
generateVerifiableGenerator :: GenerationEvidence ev => Integer -> Integer -> ev -> Word8 -> Integer

-- | Validate that the value <i>g</i> was generated by
--   <a>generateVerifiableGenerator</a> or someone using the same
--   algorithm. This is probably a good idea if you don't trust your
--   compatriot.
validateVerifiableGenerator :: GenerationEvidence ev => Integer -> Integer -> ev -> Word8 -> Integer -> Bool

module Codec.Crypto.DSA