Crypto.PubKey.ECDSA

crypton-1.0.0: Cryptography Primitives sink

License | BSD-style
Maintainer | Vincent Hanquez <vincent@snarc.org>
Stability | experimental
Portability | unknown
Safe Haskell | None
Language | Haskell2010

Crypto.PubKey.ECDSA

Contents

- Public keys
- Private keys
- Signatures
- Generation and verification

Description

Elliptic Curve Digital Signature Algorithm, with the parameterized curve implementations provided by module Crypto.ECC.

Public/private key pairs can be generated using `curveGenerateKeyPair` or decoded from binary.

WARNING: Only curve P-256 has constant-time implementation. Signature operations with P-384 and P-521 may leak the private key.

Signature verification should be safe for all curves.

Synopsis

- class EllipticCurveBasepointArith curve => EllipticCurveECDSA curve where
  - scalarIsValid :: proxy curve -> Scalar curve -> Bool
  - scalarIsZero :: proxy curve -> Scalar curve -> Bool
  - scalarInv :: proxy curve -> Scalar curve -> Maybe (Scalar curve)
  - pointX :: proxy curve -> Point curve -> Maybe (Scalar curve)
- type PublicKey curve = Point curve
- encodePublic :: (EllipticCurve curve, ByteArray bs) => proxy curve -> PublicKey curve -> bs
- decodePublic :: (EllipticCurve curve, ByteArray bs) => proxy curve -> bs -> CryptoFailable (PublicKey curve)
- toPublic :: EllipticCurveECDSA curve => proxy curve -> PrivateKey curve -> PublicKey curve
- type PrivateKey curve = Scalar curve
- encodePrivate :: (EllipticCurveECDSA curve, ByteArray bs) => proxy curve -> PrivateKey curve -> bs
- decodePrivate :: (EllipticCurveECDSA curve, ByteArray bs) => proxy curve -> bs -> CryptoFailable (PrivateKey curve)
- data Signature curve = Signature {
  - sign_r :: Scalar curve
  - sign_s :: Scalar curve
  }
- signatureFromIntegers :: EllipticCurveECDSA curve => proxy curve -> (Integer, Integer) -> CryptoFailable (Signature curve)
- signatureToIntegers :: EllipticCurveECDSA curve => proxy curve -> Signature curve -> (Integer, Integer)
- signWith :: (EllipticCurveECDSA curve, ByteArrayAccess msg, HashAlgorithm hash) => proxy curve -> Scalar curve -> PrivateKey curve -> hash -> msg -> Maybe (Signature curve)
- signDigestWith :: (EllipticCurveECDSA curve, HashAlgorithm hash) => proxy curve -> Scalar curve -> PrivateKey curve -> Digest hash -> Maybe (Signature curve)
- sign :: (EllipticCurveECDSA curve, MonadRandom m, ByteArrayAccess msg, HashAlgorithm hash) => proxy curve -> PrivateKey curve -> hash -> msg -> m (Signature curve)
- signDigest :: (EllipticCurveECDSA curve, MonadRandom m, HashAlgorithm hash) => proxy curve -> PrivateKey curve -> Digest hash -> m (Signature curve)
- verify :: (EllipticCurveECDSA curve, ByteArrayAccess msg, HashAlgorithm hash) => proxy curve -> hash -> PublicKey curve -> Signature curve -> msg -> Bool
- verifyDigest :: (EllipticCurveECDSA curve, HashAlgorithm hash) => proxy curve -> PublicKey curve -> Signature curve -> Digest hash -> Bool

# Documentation

class EllipticCurveBasepointArith curve => EllipticCurveECDSA curve where #

Elliptic curves with ECDSA capabilities.

Minimal complete definition

scalarIsValid, scalarInv, pointX

Methods

scalarIsValid :: proxy curve -> Scalar curve -> Bool #

Is a scalar in the accepted range for ECDSA

scalarIsZero :: proxy curve -> Scalar curve -> Bool #

Test whether the scalar is zero

scalarInv :: proxy curve -> Scalar curve -> Maybe (Scalar curve) #

Scalar inversion modulo the curve order

pointX :: proxy curve -> Point curve -> Maybe (Scalar curve) #

Return the point X coordinate as a scalar

#### Instances

Instances details

EllipticCurveECDSA Curve_P256R1 # |
Instance details Defined in Crypto.PubKey.ECDSA Methods scalarIsValid :: proxy Curve_P256R1 -> Scalar Curve_P256R1 -> Bool # scalarIsZero :: proxy Curve_P256R1 -> Scalar Curve_P256R1 -> Bool # scalarInv :: proxy Curve_P256R1 -> Scalar Curve_P256R1 -> Maybe (Scalar Curve_P256R1) # pointX :: proxy Curve_P256R1 -> Point Curve_P256R1 -> Maybe (Scalar Curve_P256R1) #
EllipticCurveECDSA Curve_P384R1 # |
Instance details Defined in Crypto.PubKey.ECDSA Methods scalarIsValid :: proxy Curve_P384R1 -> Scalar Curve_P384R1 -> Bool # scalarIsZero :: proxy Curve_P384R1 -> Scalar Curve_P384R1 -> Bool # scalarInv :: proxy Curve_P384R1 -> Scalar Curve_P384R1 -> Maybe (Scalar Curve_P384R1) # pointX :: proxy Curve_P384R1 -> Point Curve_P384R1 -> Maybe (Scalar Curve_P384R1) #
EllipticCurveECDSA Curve_P521R1 # |
Instance details Defined in Crypto.PubKey.ECDSA Methods scalarIsValid :: proxy Curve_P521R1 -> Scalar Curve_P521R1 -> Bool # scalarIsZero :: proxy Curve_P521R1 -> Scalar Curve_P521R1 -> Bool # scalarInv :: proxy Curve_P521R1 -> Scalar Curve_P521R1 -> Maybe (Scalar Curve_P521R1) # pointX :: proxy Curve_P521R1 -> Point Curve_P521R1 -> Maybe (Scalar Curve_P521R1) #

# Public keys

type PublicKey curve = Point curve #

ECDSA Public Key.

encodePublic :: (EllipticCurve curve, ByteArray bs) => proxy curve -> PublicKey curve -> bs #

Encode a public key into binary form, i.e. the uncompressed encoding referenced from RFC 5480 section 2.2.

decodePublic :: (EllipticCurve curve, ByteArray bs) => proxy curve -> bs -> CryptoFailable (PublicKey curve) #

Try to decode the binary form of a public key.

toPublic :: EllipticCurveECDSA curve => proxy curve -> PrivateKey curve -> PublicKey curve #

Create a public key from a private key.

# Private keys

type PrivateKey curve = Scalar curve #

ECDSA Private Key.

encodePrivate :: (EllipticCurveECDSA curve, ByteArray bs) => proxy curve -> PrivateKey curve -> bs #

Encode a private key into binary form, i.e. the `privateKey` field described in RFC 5915.

decodePrivate :: (EllipticCurveECDSA curve, ByteArray bs) => proxy curve -> bs -> CryptoFailable (PrivateKey curve) #

Try to decode the binary form of a private key.

# Signatures

data Signature curve #

Represent a ECDSA signature namely R and S.

Constructors

Signature |
Fields sign_r :: Scalar curve ECDSA r sign_s :: Scalar curve ECDSA s

#### Instances

Instances details

Show (Scalar curve) => Show (Signature curve) # |
Instance details Defined in Crypto.PubKey.ECDSA Methods showsPrec :: Int -> Signature curve -> ShowS # show :: Signature curve -> String # showList :: [Signature curve] -> ShowS #
NFData (Scalar curve) => NFData (Signature curve) # |
Instance details Defined in Crypto.PubKey.ECDSA Methods rnf :: Signature curve -> () #
Eq (Scalar curve) => Eq (Signature curve) # |
Instance details Defined in Crypto.PubKey.ECDSA Methods (==) :: Signature curve -> Signature curve -> Bool # (/=) :: Signature curve -> Signature curve -> Bool #

signatureFromIntegers :: EllipticCurveECDSA curve => proxy curve -> (Integer, Integer) -> CryptoFailable (Signature curve) #

Create a signature from integers (R, S).

signatureToIntegers :: EllipticCurveECDSA curve => proxy curve -> Signature curve -> (Integer, Integer) #

Get integers (R, S) from a signature.

The values can then be used to encode the signature to binary with ASN.1.

# Generation and verification

signWith :: (EllipticCurveECDSA curve, ByteArrayAccess msg, HashAlgorithm hash) => proxy curve -> Scalar curve -> PrivateKey curve -> hash -> msg -> Maybe (Signature curve) #

Sign message using the private key and an explicit k scalar.

signDigestWith :: (EllipticCurveECDSA curve, HashAlgorithm hash) => proxy curve -> Scalar curve -> PrivateKey curve -> Digest hash -> Maybe (Signature curve) #

Sign digest using the private key and an explicit k scalar.

sign :: (EllipticCurveECDSA curve, MonadRandom m, ByteArrayAccess msg, HashAlgorithm hash) => proxy curve -> PrivateKey curve -> hash -> msg -> m (Signature curve) #

Sign a message using hash and private key.

signDigest :: (EllipticCurveECDSA curve, MonadRandom m, HashAlgorithm hash) => proxy curve -> PrivateKey curve -> Digest hash -> m (Signature curve) #

Sign a digest using hash and private key.

verify :: (EllipticCurveECDSA curve, ByteArrayAccess msg, HashAlgorithm hash) => proxy curve -> hash -> PublicKey curve -> Signature curve -> msg -> Bool #

Verify a signature using hash and public key.

verifyDigest :: (EllipticCurveECDSA curve, HashAlgorithm hash) => proxy curve -> PublicKey curve -> Signature curve -> Digest hash -> Bool #

Verify a digest using hash and public key.