Network.Haskoin.Crypto

This package provides the elliptic curve cryptography required for creating and validating bitcoin transactions. It also provides SHA-256 and RIPEMD-160 hashing functions.

Elliptic Curve Keys

Public Keys

data PubKey

Elliptic curve public key type. Two constructors are provided for creating compressed and uncompressed public keys from a Point. The use of compressed keys is preferred as it produces shorter keys without compromising security. Uncompressed keys are supported for backwards compatibility.

Constructors

PubKey

Compressed public key

Fields

pubKeyPoint :: !Point

PubKeyU

Uncompressed public key

Fields

pubKeyPoint :: !Point

Instances

Eq PubKey

Show PubKey

Arbitrary PubKey

Binary PubKey

isValidPubKey :: PubKey -> Bool

Returns True if the public key is valid. This will check if the public key point lies on the curve.

isPubKeyU :: PubKey -> Bool

Returns True if the public key is uncompressed

derivePubKey :: PrvKey -> PubKey

Derives a public key from a private key. This function will preserve information on key compression (PrvKey becomes PubKey and PrvKeyU becomes PubKeyU)

pubKeyAddr :: PubKey -> Address

Computes an Address value from a public key

addPubKeys :: PubKey -> Hash256 -> Maybe PubKey

Add a public key to a private key defined by its Hash256 value. This will transform the private key into a public key and add the respective public key points together. This is provided as a helper for BIP32 wallet implementations. This function fails for uncompressed keys and returns Nothing if the private key value is >= than the order of the curve N.

Private Keys

data PrvKey

Elliptic curve private key type. Two constructors are provided for creating compressed or uncompressed private keys. Compression information is stored in private key WIF formats and needs to be preserved to generate the correct addresses from the corresponding public key.

Constructors

PrvKey

Compressed private key

Fields

prvKeyFieldN :: !FieldN

PrvKeyU

Uncompressed private key

Fields

prvKeyFieldN :: !FieldN

Instances

Eq PrvKey

Show PrvKey

Arbitrary PrvKey

isValidPrvKey :: Integer -> Bool

Returns True if the private key is valid. This will check if the integer value representing the private key is greater than 0 and smaller than the curve order N.

makePrvKey :: Integer -> Maybe PrvKey

Builds a compressed private key from an Integer value. Returns Nothing if the Integer would not produce a valid private key. For security, the Integer needs to be generated from a random source with sufficient entropy.

makePrvKeyU :: Integer -> Maybe PrvKey

Builds an uncompressed private key from an Integer value. Returns Nothing if the Integer would not produce a valid private key. For security, the Integer needs to be generated from a random source with sufficient entropy.

fromPrvKey :: PrvKey -> Integer

Returns the Integer value of a private key

isPrvKeyU :: PrvKey -> Bool

Returns True of the private key is uncompressed

addPrvKeys :: PrvKey -> Hash256 -> Maybe PrvKey

Add two private keys together. One of the keys is defined by a Hash256. The functions fails on uncompressed private keys and return Nothing if the Hash256 is smaller than the order of the curve N. This is provided as a helper for implementing BIP32 wallets.

putPrvKey :: PrvKey -> Put

Serialize a private key into the Data.Binary.Put monad as a 32 byte big endian ByteString. This is useful when a constant length serialization format for private keys is required

getPrvKey :: Get PrvKey

Deserializes a compressed private key from the Data.Binary.Get monad as a 32 byte big endian ByteString.

getPrvKeyU :: Get PrvKey

Deserializes an uncompressed private key from the Data.Binary.Get monad as a 32 byte big endian ByteString

fromWIF :: String -> Maybe PrvKey

Decodes a private key from a WIF encoded String. This function can fail if the input string does not decode correctly as a base 58 string or if the checksum fails. http://en.bitcoin.it/wiki/Wallet_import_format

toWIF :: PrvKey -> String

Encodes a private key into WIF format

ECDSA

SecretT Monad

The SecretT monad is a monadic wrapper around HMAC DRBG (deterministic random byte generator) using SHA-256. The implementation is provided in Hash and the specification is defined in http://csrc.nist.gov/publications/nistpubs/800-90A/SP800-90A.pdf. The SecretT monad is used to generate random private keys and random nonces for ECDSA signatures.

type SecretT m a = StateT (SecretState m) m a

StateT monad stack tracking the internal state of HMAC DRBG pseudo random number generator using SHA-256. The SecretT monad is run with the withSource function by providing it a source of entropy.

withSource :: Monad m => (Int -> m ByteString) -> SecretT m a -> m a

Run a SecretT monad by providing it a source of entropy. You can use devURandom, devRandom or provide your own entropy source function.

devURandom :: Int -> IO ByteString

/dev/urandom entropy source. This is only available on machines supporting it. This function is meant to be used together with withSource.

devRandom :: Int -> IO ByteString

/dev/random entropy source. This is only available on machines supporting it. This function is meant to be used together with withSource.

genPrvKey :: Monad m => SecretT m PrvKey

Produce a new PrvKey randomly from the SecretT monad.

Signatures

Elliptic curve cryptography standards are defined in http://www.secg.org/download/aid-780/sec1-v2.pdf

data Signature

Data type representing an ECDSA signature.

Instances

Eq Signature

Show Signature

Arbitrary Signature

Binary Signature

signMsg :: Monad m => Hash256 -> PrvKey -> SecretT m Signature

Safely sign a message inside the SecretT monad. The SecretT monad will generate a new nonce for each signature.

detSignMsg :: Hash256 -> PrvKey -> Signature

Sign a message using ECDSA deterministic signatures as defined by RFC 6979 http://tools.ietf.org/html/rfc6979

verifySig :: Hash256 -> Signature -> PubKey -> Bool

Verify an ECDSA signature

isCanonicalHalfOrder :: Signature -> Bool

Returns True if the S component of a Signature is <= order/2. Signatures need to pass this test to be canonical.

Hash functions

type Hash512 = Ring Mod512

Data type representing a 512 bit unsigned integer. It is implemented as an Integer modulo 2^512.

type Hash256 = Ring Mod256

Data type representing a 256 bit unsigned integer. It is implemented as an Integer modulo 2^256.

type Hash160 = Ring Mod160

Data type representing a 160 bit unsigned integer. It is implemented as an Integer modulo 2^160.

data CheckSum32

Data type representing a 32 bit checksum

Instances

Eq CheckSum32

Show CheckSum32

Arbitrary CheckSum32

Binary CheckSum32

hash512 :: ByteString -> Hash512

Computes SHA-512.

hash512BS :: ByteString -> ByteString

Computes SHA-512 and returns the result as a bytestring.

hash256 :: ByteString -> Hash256

Computes SHA-256.

hash256BS :: ByteString -> ByteString

Computes SHA-256 and returns the result as a bytestring.

hash160 :: ByteString -> Hash160

Computes RIPEMD-160.

hash160BS :: ByteString -> ByteString

Computes RIPEMD-160 and returns the result as a bytestring.

doubleHash256 :: ByteString -> Hash256

Computes two rounds of SHA-256.

doubleHash256BS :: ByteString -> ByteString

Computes two rounds of SHA-256 and returns the result as a bytestring.

chksum32 :: ByteString -> CheckSum32

Computes a 32 bit checksum.

hmac512 :: ByteString -> ByteString -> Hash512

Computes HMAC over SHA-512.

hmac512BS :: ByteString -> ByteString -> ByteString

Computes HMAC over SHA-512 and return the result as a bytestring.

hmac256 :: ByteString -> ByteString -> Hash256

Computes HMAC over SHA-256.

hmac256BS :: ByteString -> ByteString -> ByteString

Computes HMAC over SHA-256 and return the result as a bytestring.

split512 :: Hash512 -> (Hash256, Hash256)

Split a Hash512 into a pair of Hash256.

join512 :: (Hash256, Hash256) -> Hash512

Join a pair of Hash256 into a Hash512.

Base58 and Addresses

data Address

Data type representing a Bitcoin address

Constructors

PubKeyAddress

Public Key Hash Address

Fields

getAddress :: Hash160

ScriptAddress

Script Hash Address

Fields

getAddress :: Hash160

Instances

Eq Address

Show Address

Arbitrary Address

base58ToAddr :: String -> Maybe Address

Decodes an Address from a base58 encoded String. This function can fail if the String is not properly encoded as base58 or the checksum fails.

addrToBase58 :: Address -> String

Transforms an Address into a base58 encoded String

encodeBase58 :: ByteString -> ByteString

Encode a bytestring to a base 58 representation.

decodeBase58 :: ByteString -> Maybe ByteString

Decode a base 58 encoded bytestring. This can fail if the input bytestring contains invalid base 58 characters such as 0,O,l,I

encodeBase58Check :: ByteString -> ByteString

Computes a checksum for the input bytestring and encodes the input and the checksum to a base 58 representation.

decodeBase58Check :: ByteString -> Maybe ByteString

Decode a base 58 encoded bytestring that contains a checksum. This function returns Nothing if the input bytestring contains invalid base 58 characters or if the checksum fails.