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


-- | Cryptographic primitives used in the Cardano project
--   
--   Cryptographic primitives used in the Cardano project
@package cardano-crypto-wrapper
@version 1.3.0


-- | Hashing capabilities.
module Cardano.Crypto.Hashing

-- | Hash wrapper with phantom type for more type-safety
--   
--   Made abstract in order to support different algorithms
data AbstractHash algo a

-- | Class representing hashing algorithms.
--   
--   The interface presented here is update in place and lowlevel. the Hash
--   module takes care of hidding the mutable interface properly.
class HashAlgorithm a

-- | Hash the <a>ToCBOR</a>-serialised version of a value Once this is no
--   longer used outside this module it should be made private.
abstractHash :: (HashAlgorithm algo, ToCBOR a) => a -> AbstractHash algo a

-- | Hash a lazy <a>LByteString</a>
--   
--   You can choose the phantom type, hence the "unsafe".
unsafeAbstractHash :: HashAlgorithm algo => LByteString -> AbstractHash algo a

-- | Make an <a>AbstractHash</a> from a <a>Digest</a> for the same
--   <a>HashAlgorithm</a>.
abstractHashFromDigest :: Digest algo -> AbstractHash algo a

-- | Make an <a>AbstractHash</a> from the bytes representation of the hash.
--   It will fail if given the wrong number of bytes for the choice of
--   <a>HashAlgorithm</a>.
abstractHashFromBytes :: forall algo a. HashAlgorithm algo => ByteString -> Maybe (AbstractHash algo a)

-- | Like <tt>abstractHashFromDigestBytes</tt> but the number of bytes
--   provided <i>must</i> be correct for the choice of
--   <a>HashAlgorithm</a>.
unsafeAbstractHashFromBytes :: ByteString -> AbstractHash algo a

-- | The bytes representation of the hash value.
abstractHashToBytes :: AbstractHash algo a -> ByteString

-- | The <a>ShortByteString</a> representation of the hash value.
unsafeAbstractHashFromShort :: ShortByteString -> AbstractHash algo a

-- | The <a>ShortByteString</a> representation of the hash value.
abstractHashToShort :: AbstractHash algo a -> ShortByteString

-- | Parses given hash in base16 form.
decodeAbstractHash :: HashAlgorithm algo => Text -> Either Text (AbstractHash algo a)

-- | The type of our commonly used hash, Blake2b 256
type Hash = AbstractHash Blake2b_256

-- | The hash of a value, serialised via <a>ToCBOR</a>.

-- | <i>Deprecated: Use serializeCborHash or hash the annotation
--   instead.</i>
hash :: ToCBOR a => a -> Hash a

-- | The hash of a value's annotation
hashDecoded :: Decoded t => t -> Hash (BaseType t)

-- | Hash a bytestring
hashRaw :: ByteString -> Hash Raw

-- | The hash of a value, serialised via <a>ToCBOR</a>.
serializeCborHash :: ToCBOR a => a -> Hash a

-- | Make a hash from it bytes representation. It must be a 32-byte
--   bytestring. The size is checked.
hashFromBytes :: ByteString -> Maybe (Hash a)

-- | Make a hash from a 32-byte bytestring. It must be exactly 32 bytes.
unsafeHashFromBytes :: ByteString -> Hash a

-- | The bytes representation of the hash value.
hashToBytes :: AbstractHash algo a -> ByteString

-- | Parses given hash in base16 form.
decodeHash :: Text -> Either Text (Hash a)

-- | Specialized formatter for <a>Hash</a>.
hashHexF :: Format r (AbstractHash algo a -> r)

-- | Smart formatter for <a>Hash</a> to show only first <tt>16</tt>
--   characters of <a>Hash</a>.
mediumHashF :: Format r (AbstractHash algo a -> r)

-- | Smart formatter for <a>Hash</a> to show only first <tt>8</tt>
--   characters of <a>Hash</a>.
shortHashF :: Format r (AbstractHash algo a -> r)
instance NoThunks.Class.NoThunks (Cardano.Crypto.Hashing.AbstractHash algo a)
instance Control.DeepSeq.NFData (Cardano.Crypto.Hashing.AbstractHash algo a)
instance GHC.Generics.Generic (Cardano.Crypto.Hashing.AbstractHash algo a)
instance GHC.Classes.Ord (Cardano.Crypto.Hashing.AbstractHash algo a)
instance GHC.Classes.Eq (Cardano.Crypto.Hashing.AbstractHash algo a)
instance GHC.Show.Show (Cardano.Crypto.Hashing.AbstractHash algo a)
instance Crypto.Hash.Types.HashAlgorithm algo => GHC.Read.Read (Cardano.Crypto.Hashing.AbstractHash algo a)
instance Formatting.Buildable.Buildable (Cardano.Crypto.Hashing.AbstractHash algo a)
instance Data.Aeson.Types.ToJSON.ToJSON (Cardano.Crypto.Hashing.AbstractHash algo a)
instance Crypto.Hash.Types.HashAlgorithm algo => Data.Aeson.Types.FromJSON.FromJSON (Cardano.Crypto.Hashing.AbstractHash algo a)
instance (Crypto.Hash.Types.HashAlgorithm algo, Data.Aeson.Types.FromJSON.FromJSON (Cardano.Crypto.Hashing.AbstractHash algo a)) => Data.Aeson.Types.FromJSON.FromJSONKey (Cardano.Crypto.Hashing.AbstractHash algo a)
instance Data.Aeson.Types.ToJSON.ToJSONKey (Cardano.Crypto.Hashing.AbstractHash algo a)
instance (Data.Typeable.Internal.Typeable algo, Data.Typeable.Internal.Typeable a, Crypto.Hash.Types.HashAlgorithm algo) => Cardano.Binary.ToCBOR.ToCBOR (Cardano.Crypto.Hashing.AbstractHash algo a)
instance (Data.Typeable.Internal.Typeable algo, Data.Typeable.Internal.Typeable a, Crypto.Hash.Types.HashAlgorithm algo) => Cardano.Binary.FromCBOR.FromCBOR (Cardano.Crypto.Hashing.AbstractHash algo a)
instance Cardano.Prelude.HeapWords.HeapWords (Cardano.Crypto.Hashing.AbstractHash algo a)

module Cardano.Crypto.Orphans
instance Data.Aeson.Types.FromJSON.FromJSON Crypto.PubKey.Ed25519.PublicKey
instance Data.Aeson.Types.ToJSON.ToJSON Crypto.PubKey.Ed25519.PublicKey
instance Data.Aeson.Types.FromJSON.FromJSON Crypto.PubKey.Ed25519.Signature
instance Data.Aeson.Types.ToJSON.ToJSON Crypto.PubKey.Ed25519.Signature
instance Cardano.Binary.ToCBOR.ToCBOR Crypto.PubKey.Ed25519.PublicKey
instance Cardano.Binary.FromCBOR.FromCBOR Crypto.PubKey.Ed25519.PublicKey
instance Cardano.Binary.ToCBOR.ToCBOR Crypto.PubKey.Ed25519.SecretKey
instance Cardano.Binary.FromCBOR.FromCBOR Crypto.PubKey.Ed25519.SecretKey
instance Cardano.Binary.ToCBOR.ToCBOR Crypto.PubKey.Ed25519.Signature
instance Cardano.Binary.FromCBOR.FromCBOR Crypto.PubKey.Ed25519.Signature

module Cardano.Crypto.ProtocolMagic
newtype ProtocolMagicId
ProtocolMagicId :: Word32 -> ProtocolMagicId
[unProtocolMagicId] :: ProtocolMagicId -> Word32
type ProtocolMagic = AProtocolMagic ()

-- | Magic number which should differ for different clusters. It's defined
--   here, because it's used for signing. It also used for other things (e.
--   g. it's part of a serialized block).
--   
--   mhueschen: As part of CO-353 I am adding
--   <a>getRequiresNetworkMagic</a> in order to pipe configuration to
--   functions which must generate &amp; verify Addresses (which now must
--   be aware of <tt>NetworkMagic</tt>).
data AProtocolMagic a
AProtocolMagic :: !Annotated ProtocolMagicId a -> !RequiresNetworkMagic -> AProtocolMagic a
[getAProtocolMagicId] :: AProtocolMagic a -> !Annotated ProtocolMagicId a
[getRequiresNetworkMagic] :: AProtocolMagic a -> !RequiresNetworkMagic

-- | Bool-isomorphic flag indicating whether we're on testnet or
--   mainnet/staging.
data RequiresNetworkMagic
RequiresNoMagic :: RequiresNetworkMagic
RequiresMagic :: RequiresNetworkMagic
getProtocolMagic :: AProtocolMagic a -> Word32
getProtocolMagicId :: AProtocolMagic a -> ProtocolMagicId
instance NoThunks.Class.NoThunks Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance Control.DeepSeq.NFData Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance Cardano.Binary.ToCBOR.ToCBOR Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance Cardano.Binary.FromCBOR.FromCBOR Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance GHC.Generics.Generic Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance GHC.Classes.Eq Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance GHC.Show.Show Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance NoThunks.Class.NoThunks Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance Control.DeepSeq.NFData Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance GHC.Generics.Generic Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance GHC.Classes.Eq Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance GHC.Show.Show Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance NoThunks.Class.NoThunks a => NoThunks.Class.NoThunks (Cardano.Crypto.ProtocolMagic.AProtocolMagic a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Cardano.Crypto.ProtocolMagic.AProtocolMagic a)
instance GHC.Generics.Generic (Cardano.Crypto.ProtocolMagic.AProtocolMagic a)
instance GHC.Show.Show a => GHC.Show.Show (Cardano.Crypto.ProtocolMagic.AProtocolMagic a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Cardano.Crypto.ProtocolMagic.AProtocolMagic a)
instance Data.Aeson.Types.ToJSON.ToJSON Cardano.Crypto.ProtocolMagic.ProtocolMagic
instance Data.Aeson.Types.FromJSON.FromJSON Cardano.Crypto.ProtocolMagic.ProtocolMagic
instance Data.Aeson.Types.ToJSON.ToJSON Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance Data.Aeson.Types.FromJSON.FromJSON Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.ToJSON m Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance Control.Monad.Error.Class.MonadError Cardano.Prelude.Json.Canonical.SchemaError m => Text.JSON.Canonical.Class.FromJSON m Cardano.Crypto.ProtocolMagic.RequiresNetworkMagic
instance Data.Aeson.Types.ToJSON.ToJSON Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance Data.Aeson.Types.FromJSON.FromJSON Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance GHC.Base.Monad m => Text.JSON.Canonical.Class.ToJSON m Cardano.Crypto.ProtocolMagic.ProtocolMagicId
instance Control.Monad.Error.Class.MonadError Cardano.Prelude.Json.Canonical.SchemaError m => Text.JSON.Canonical.Class.FromJSON m Cardano.Crypto.ProtocolMagic.ProtocolMagicId


-- | Secure generation of random numbers and <a>ByteString</a>s
module Cardano.Crypto.Random

-- | You can use <a>runSecureRandom</a> on any <a>MonadRandom</a>
--   computation to use the operating system entropy source to satisfy
--   every request for randomness. That is, this does not use a fixed
--   entropy pool shared across all requests; it gets entropy from the
--   operating system for every request.
--   
--   This is suitable for key generation but is inappropriate for other
--   uses since it can quickly drain the operating system entropy.
newtype SecureRandom a
SecureRandom :: IO a -> SecureRandom a
[runSecureRandom] :: SecureRandom a -> IO a

-- | You can use <a>deterministic</a> on any <a>MonadRandom</a> computation
--   to make it use a seed (hopefully produced by a Really Secure™
--   randomness source). The seed has to have enough entropy to make this
--   function secure.
deterministic :: ByteString -> MonadPseudoRandom ChaChaDRG a -> a

-- | Generate a random number in range [0, n)
--   
--   We want to avoid modulo bias, so we use the arc4random_uniform
--   implementation (http:/<i>stackoverflow.com</i>a<i>20051580</i>615030).
--   Specifically, we repeatedly generate a random number in range [0, 2^x)
--   until we hit on something outside of [0, 2^x mod n), which means that
--   it'll be in range [2^x mod n, 2^x). The amount of numbers in this
--   interval is guaranteed to be divisible by n, and thus applying
--   <a>mod</a> to it will be safe.
randomNumber :: forall m. MonadRandom m => Integer -> m Integer

-- | Generate a random number in range [a, b]
randomNumberInRange :: MonadRandom m => Integer -> Integer -> m Integer
instance GHC.Base.Monad Cardano.Crypto.Random.SecureRandom
instance GHC.Base.Applicative Cardano.Crypto.Random.SecureRandom
instance GHC.Base.Functor Cardano.Crypto.Random.SecureRandom
instance Crypto.Random.Types.MonadRandom Cardano.Crypto.Random.SecureRandom

module Cardano.Crypto.Signing.Redeem

-- | Wrapper around <a>Signature</a>
newtype RedeemSignature a
RedeemSignature :: Signature -> RedeemSignature a

-- | Encode something with <a>ToCBOR</a> and sign it
redeemSign :: ToCBOR a => ProtocolMagicId -> SignTag -> RedeemSigningKey -> a -> RedeemSignature a

-- | Alias for constructor
redeemSignRaw :: ProtocolMagicId -> Maybe SignTag -> RedeemSigningKey -> ByteString -> RedeemSignature Raw

-- | Verify a redeem signature
verifyRedeemSig :: ToCBOR a => ProtocolMagicId -> SignTag -> RedeemVerificationKey -> a -> RedeemSignature a -> Bool
verifyRedeemSigDecoded :: Decoded t => Annotated ProtocolMagicId ByteString -> SignTag -> RedeemVerificationKey -> t -> RedeemSignature (BaseType t) -> Bool

-- | Verify raw <a>ByteString</a>
verifyRedeemSigRaw :: RedeemVerificationKey -> ByteString -> RedeemSignature Raw -> Bool

-- | Wrapper around <a>SecretKey</a>.
newtype RedeemSigningKey
RedeemSigningKey :: SecretKey -> RedeemSigningKey

-- | Verification key derivation function.
redeemToVerification :: RedeemSigningKey -> RedeemVerificationKey

-- | Wrapper around <a>PublicKey</a>.
newtype RedeemVerificationKey
RedeemVerificationKey :: PublicKey -> RedeemVerificationKey
redeemVKB64F :: Format r (RedeemVerificationKey -> r)

-- | Base64url Format for <a>RedeemVerificationKey</a>.
redeemVKB64UrlF :: Format r (RedeemVerificationKey -> r)
redeemVKB64ShortF :: Format r (RedeemVerificationKey -> r)

-- | Read the text into a redeeming verification key. The key should be in
--   AVVM format which is base64(url). This function must be inverse of
--   redeemVKB64UrlF formatter.
fromAvvmVK :: Text -> Either AvvmVKError RedeemVerificationKey
fromVerificationKeyToByteString :: PublicKey -> ByteString

-- | Creates a verification key from 32 byte bytestring, fails with
--   <tt>error</tt> otherwise
redeemVKBuild :: ByteString -> RedeemVerificationKey

-- | Generate a key pair. It's recommended to run it with
--   <tt>runSecureRandom</tt> from <a>Cardano.Crypto.Random</a> because the
--   OpenSSL generator is probably safer than the default IO generator.
redeemKeyGen :: MonadRandom m => m (RedeemVerificationKey, RedeemSigningKey)

-- | Create key pair deterministically from 32 bytes
redeemDeterministicKeyGen :: ByteString -> Maybe (RedeemVerificationKey, RedeemSigningKey)
data CompactRedeemVerificationKey
CompactRedeemVerificationKey :: {-# UNPACK #-} !Word64 -> {-# UNPACK #-} !Word64 -> {-# UNPACK #-} !Word64 -> {-# UNPACK #-} !Word64 -> CompactRedeemVerificationKey
fromCompactRedeemVerificationKey :: CompactRedeemVerificationKey -> RedeemVerificationKey
toCompactRedeemVerificationKey :: RedeemVerificationKey -> CompactRedeemVerificationKey

module Cardano.Crypto.Signing.Safe

-- | SafeSigner datatype to encapsulate sensitive data
data SafeSigner
SafeSigner :: !SigningKey -> !PassPhrase -> SafeSigner
noPassSafeSigner :: SigningKey -> SafeSigner
safeToVerification :: SafeSigner -> VerificationKey
newtype PassPhrase
PassPhrase :: ScrubbedBytes -> PassPhrase

-- | Empty passphrase used in development
emptyPassphrase :: PassPhrase
passphraseLength :: Int
safeDeterministicKeyGen :: ByteString -> PassPhrase -> (VerificationKey, SigningKey)
safeKeyGen :: MonadRandom m => PassPhrase -> m (VerificationKey, SigningKey)

module Cardano.Crypto.Signing

-- | To protect against replay attacks (i.e. when an attacker intercepts a
--   signed piece of data and later sends it again), we add a tag to all
--   data that we sign. This ensures that even if some bytestring can be
--   deserialized into two different types of messages (A and B), the
--   attacker can't take message A and send it as message B.
--   
--   We also automatically add the network tag (<tt>protocolMagic</tt>)
--   whenever it makes sense, to ensure that things intended for testnet
--   won't work for mainnet.
data SignTag

-- | Anything (to be used for testing only)
SignForTestingOnly :: SignTag

-- | Tx: <tt>TxSigData</tt>
SignTx :: SignTag

-- | Redeem tx: <tt>TxSigData</tt>
SignRedeemTx :: SignTag

-- | Vss certificate: <tt>(VssVerificationKey, EpochNumber)</tt>
SignVssCert :: SignTag

-- | Update proposal: <tt>UpdateProposalToSign</tt>
SignUSProposal :: SignTag

-- | Commitment: <tt>(EpochNumber, Commitment)</tt>
SignCommitment :: SignTag

-- | US proposal vote: <tt>(UpId, Bool)</tt>
SignUSVote :: SignTag

-- | Block header: <tt>ToSign</tt>
--   
--   This constructor takes the <a>VerificationKey</a> of the delegation
--   certificate issuer, which is prepended to the signature as part of the
--   sign tag
SignBlock :: VerificationKey -> SignTag

-- | Certificate: <tt>Certificate</tt>
SignCertificate :: SignTag

-- | Get magic bytes corresponding to a <a>SignTag</a>. Guaranteed to be
--   different (and begin with a different byte) for different tags.
signTag :: ProtocolMagicId -> SignTag -> ByteString

-- | Get magic bytes corresponding to a <a>SignTag</a>, taking
--   <tt>ProtocolMagic</tt> bytes from the annotation
signTagDecoded :: Annotated ProtocolMagicId ByteString -> SignTag -> ByteString

-- | Wrapper around <a>XSignature</a>
newtype Signature a
Signature :: XSignature -> Signature a
toCBORXSignature :: XSignature -> Encoding
fromCBORXSignature :: Decoder s XSignature

-- | Formatter for <a>Signature</a> to show it in hex.
fullSignatureHexF :: Format r (Signature a -> r)

-- | Parse <a>Signature</a> from base16 encoded string.
parseFullSignature :: Text -> Either SignatureParseError (Signature a)

-- | Encode something with <a>ToCBOR</a> and sign it
sign :: ToCBOR a => ProtocolMagicId -> SignTag -> SigningKey -> a -> Signature a

-- | Like <a>sign</a> but without the <a>ToCBOR</a> constraint
signEncoded :: ProtocolMagicId -> SignTag -> SigningKey -> Encoding -> Signature a

-- | Sign a <a>Raw</a> bytestring
signRaw :: ProtocolMagicId -> Maybe SignTag -> SigningKey -> ByteString -> Signature Raw
safeSign :: ToCBOR a => ProtocolMagicId -> SignTag -> SafeSigner -> a -> Signature a
safeSignRaw :: ProtocolMagicId -> Maybe SignTag -> SafeSigner -> ByteString -> Signature Raw

-- | Verify a signature
verifySignature :: (a -> Encoding) -> ProtocolMagicId -> SignTag -> VerificationKey -> a -> Signature a -> Bool

-- | Verify a signature
verifySignatureDecoded :: Decoded t => Annotated ProtocolMagicId ByteString -> SignTag -> VerificationKey -> t -> Signature (BaseType t) -> Bool

-- | Verify <a>Raw</a> signature
verifySignatureRaw :: VerificationKey -> ByteString -> Signature Raw -> Bool

-- | Wrapper around <a>XPrv</a>.
newtype SigningKey
SigningKey :: XPrv -> SigningKey
[unSigningKey] :: SigningKey -> XPrv

-- | Generate a verification key from a signing key. Fast (it just drops
--   some bytes off the signing key).
toVerification :: SigningKey -> VerificationKey
toCBORXPrv :: XPrv -> Encoding
fromCBORXPrv :: Decoder s XPrv

-- | Wrapper around <a>XPub</a>.
newtype VerificationKey
VerificationKey :: XPub -> VerificationKey
[unVerificationKey] :: VerificationKey -> XPub

-- | <a>Builder</a> for <a>VerificationKey</a> to show it in base64 encoded
--   form.
formatFullVerificationKey :: VerificationKey -> Builder

-- | Formatter for <a>VerificationKey</a> to show it in base64.
fullVerificationKeyF :: Format r (VerificationKey -> r)

-- | Formatter for <a>VerificationKey</a> to show it in hex.
fullVerificationKeyHexF :: Format r (VerificationKey -> r)

-- | Formatter for <a>VerificationKey</a> to show it in hex, but only first
--   8 chars.
shortVerificationKeyHexF :: Format r (VerificationKey -> r)

-- | Parse <a>VerificationKey</a> from base64 encoded string
parseFullVerificationKey :: Text -> Either VerificationKeyParseError VerificationKey

-- | Generate a key pair. It's recommended to run it with
--   <tt>runSecureRandom</tt> from <a>Cardano.Crypto.Random</a> because the
--   OpenSSL generator is probably safer than the default IO generator.
keyGen :: MonadRandom m => m (VerificationKey, SigningKey)

-- | Create key pair deterministically from 32 bytes.
deterministicKeyGen :: ByteString -> (VerificationKey, SigningKey)

module Cardano.Crypto
