libghc-crypto-pubkey-doc 0.2.8-7 / usr / share / doc / libghc-crypto-pubkey-doc / html / crypto-pubkey.txt

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


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


-- | 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.
--   
--   This perform the following calculation: &gt; lambda = (3 * xp ^ 2 + a)
--   / 2 yp &gt; xr = lambda ^ 2 - 2 xp &gt; yr = lambda (xp - xr) - yp
--   
--   With binary curve: &gt; xp == 0 =&gt; P = O &gt; otherwise =&gt; &gt;
--   s = xp + (yp / xp) &gt; xr = s ^ 2 + s + a &gt; yr = xp ^ 2 + (s+1) *
--   xr
pointDouble :: Curve -> Point -> Point

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

-- | Check if a point is the point at infinity.
isPointAtInfinity :: Point -> Bool

-- | check if a point is on specific curve
--   
--   This perform three checks:
--   
--   <ul>
--   <li>x is not out of range</li>
--   <li>y is not out of range</li>
--   <li>the equation <tt>y^2 = x^3 + a*x + b (mod p)</tt> holds</li>
--   </ul>
isPointValid :: Curve -> Point -> Bool

module Crypto.PubKey.ECC.DH

-- | Define either a binary curve or a prime curve.
data Curve :: *

-- | ECC Public Point
type PublicPoint = Point

-- | ECC Private Number
type PrivateNumber = Integer

-- | Represent Diffie Hellman shared secret.
newtype SharedKey :: *
SharedKey :: Integer -> SharedKey

-- | Generating a private number d.
generatePrivate :: CPRG g => g -> Curve -> (PrivateNumber, g)

-- | Generating a public point Q.
calculatePublic :: Curve -> PrivateNumber -> PublicPoint

-- | Generating a shared key using our private number and the other party
--   public point.
getShared :: Curve -> PrivateNumber -> PublicPoint -> SharedKey


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


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


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


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


module Crypto.PubKey.MaskGenFunction

-- | Represent a mask generation algorithm
type MaskGenAlgorithm = HashFunction  hash function to use -> ByteString  seed -> Int  length to generate -> ByteString

-- | Mask generation algorithm MGF1
mgf1 :: MaskGenAlgorithm


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


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