ecies

README

This implementation is direct fork of Kylom's implementation. I claim no authorship over this code apart from some minor modifications. Just works in Linux and Mac

ecies implements the Elliptic Curve Integrated Encryption Scheme.

The package is designed to be compliant with the appropriate NIST standards, and therefore doesn't support the full SEC 1 algorithm set.

STATUS:

ecies should be ready for use. The ASN.1 support is only complete so far as to supported the listed algorithms before.

CAVEATS

1. CMAC support is currently not present.

SUPPORTED ALGORITHMS

    SYMMETRIC CIPHERS               HASH FUNCTIONS
         AES128                         SHA-1
         AES192                        SHA-224
         AES256                        SHA-256
                                       SHA-384
    ELLIPTIC CURVE                     SHA-512
         P256
         P384       KEY DERIVATION FUNCTION
         P521        NIST SP 800-65a Concatenation KDF

Curve P224 isn't supported because it does not provide a minimum security level of AES128 with HMAC-SHA1. According to NIST SP 800-57, the security level of P224 is 112 bits of security. Symmetric ciphers use CTR-mode; message tags are computed using HMAC- function.

CURVE SELECTION

According to NIST SP 800-57, the following curves should be selected:

+----------------+-------+
| SYMMETRIC SIZE | CURVE |
+----------------+-------+
|     128-bit    |  P256 |
+----------------+-------+
|     192-bit    |  P384 |
+----------------+-------+
|     256-bit    |  P521 |
+----------------+-------+

TODO

1. Look at serialising the parameters with the SEC 1 ASN.1 module.
2. Validate ASN.1 formats with SEC 1.

TEST VECTORS

The only test vectors I've found so far date from 1993, predating AES and including only 163-bit curves. Therefore, there are no published test vectors to compare to.

Install library

go get -u  github.com/hendry19901990/ecies

Sample

package main

import (
  "fmt"
  "crypto/rand"
  "github.com/hendry19901990/ecies"
)

func main() {
  //Load Private Key from Random
  prv1, _ := ecies.GenerateKey(rand.Reader, ecies.DefaultCurve, nil)
  //Load Private Key from string of sha256
  prv2, _ := ecies.HexKey("4067d588f8866d1820c3bb1315c9ce5091b656935c8efc3220dcb51bb48460e0")

  message := []byte("Hello, world.") // plain text
  ct, err := prv1.EncryptShared(rand.Reader, &prv2.PublicKey, message, nil, nil)
  if err != nil {
    fmt.Println(err.Error())
    return
  }

  fmt.Printf("Message encrypt:  %v\n", ct) // ciphered text

  pt, err := prv2.Decrypt(ct, nil, nil)
  if err != nil {
    fmt.Println(err.Error())
    return
  }

  fmt.Printf("Message decrypt:  %s\n", string(pt)) // plain text

}

LICENSE

ecies is released under the same license as the Go source code. See the LICENSE file for details.

REFERENCES

• SEC (Standard for Efficient Cryptography) 1, version 2.0: Elliptic Curve Cryptography; Certicom, May 2009. http://www.secg.org/sec1-v2.pdf
• GEC (Guidelines for Efficient Cryptography) 2, version 0.3: Test Vectors for SEC 1; Certicom, September 1999. http://read.pudn.com/downloads168/doc/772358/TestVectorsforSEC%201-gec2.pdf
• NIST SP 800-56a: Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography. National Institute of Standards and Technology, May 2007. http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf
• Suite B Implementer’s Guide to NIST SP 800-56A. National Security Agency, July 28, 2009. http://www.nsa.gov/ia/_files/SuiteB_Implementer_G-113808.pdf
• NIST SP 800-57: Recommendation for Key Management – Part 1: General (Revision 3). National Institute of Standards and Technology, July 2012. http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf

Documentation

Index

• Variables
• func AddParamsForCurve(curve elliptic.Curve, params *ECIESParams)
• func Encrypt(rand io.Reader, pub *PublicKey, m, s1, s2 []byte) (ct []byte, err error)
• func MaxSharedKeyLength(pub *PublicKey) int
• type ECIESParams
  • func ParamsFromCurve(curve elliptic.Curve) (params *ECIESParams)
• type PrivateKey
  • func GenerateKey(rand io.Reader, curve elliptic.Curve, params *ECIESParams) (prv *PrivateKey, err error)
  • func HexKey(prv string) (*PrivateKey, error)
  • func ImportECDSA(prv *ecdsa.PrivateKey) *PrivateKey
  • func (prv *PrivateKey) Decrypt(c, s1, s2 []byte) (m []byte, err error)
  • func (prv *PrivateKey) EncryptShared(rand io.Reader, pub *PublicKey, m, s1, s2 []byte) (ct []byte, err error)
  • func (prv *PrivateKey) ExportECDSA() *ecdsa.PrivateKey
  • func (prv *PrivateKey) GenerateShared(pub *PublicKey, skLen, macLen int) (sk []byte, err error)
  • func (prv *PrivateKey) PrivateKeyHex() string
  • func (prv *PrivateKey) PublicKeyHex() string
• type PublicKey
  • func Hex2PublicKey(hexkey string) (*PublicKey, error)
  • func ImportECDSAPublic(pub *ecdsa.PublicKey) *PublicKey
  • func (pub *PublicKey) ExportECDSA() *ecdsa.PublicKey

Variables

var (
	ErrImport                     = fmt.Errorf("ecies: failed to import key")
	ErrInvalidCurve               = fmt.Errorf("ecies: invalid elliptic curve")
	ErrInvalidParams              = fmt.Errorf("ecies: invalid ECIES parameters")
	ErrInvalidPublicKey           = fmt.Errorf("ecies: invalid public key")
	ErrSharedKeyIsPointAtInfinity = fmt.Errorf("ecies: shared key is point at infinity")
	ErrSharedKeyTooBig            = fmt.Errorf("ecies: shared key params are too big")
	InvalidHex                    = fmt.Errorf("ecies: invalid hex string")
)

var (
	ErrKeyDataTooLong = fmt.Errorf("ecies: can't supply requested key data")
	ErrSharedTooLong  = fmt.Errorf("ecies: shared secret is too long")
	ErrInvalidMessage = fmt.Errorf("ecies: invalid message")
)

var (
	DefaultCurve                  = ethcrypto.S256()
	ErrUnsupportedECDHAlgorithm   = fmt.Errorf("ecies: unsupported ECDH algorithm")
	ErrUnsupportedECIESParameters = fmt.Errorf("ecies: unsupported ECIES parameters")
)

var (
	ECIES_AES128_SHA256 = &ECIESParams{
		Hash:      sha256.New,
		hashAlgo:  crypto.SHA256,
		Cipher:    aes.NewCipher,
		BlockSize: aes.BlockSize,
		KeyLen:    16,
	}

	ECIES_AES256_SHA256 = &ECIESParams{
		Hash:      sha256.New,
		hashAlgo:  crypto.SHA256,
		Cipher:    aes.NewCipher,
		BlockSize: aes.BlockSize,
		KeyLen:    32,
	}

	ECIES_AES256_SHA384 = &ECIESParams{
		Hash:      sha512.New384,
		hashAlgo:  crypto.SHA384,
		Cipher:    aes.NewCipher,
		BlockSize: aes.BlockSize,
		KeyLen:    32,
	}

	ECIES_AES256_SHA512 = &ECIESParams{
		Hash:      sha512.New,
		hashAlgo:  crypto.SHA512,
		Cipher:    aes.NewCipher,
		BlockSize: aes.BlockSize,
		KeyLen:    32,
	}
)

Functions

func AddParamsForCurve

func AddParamsForCurve(curve elliptic.Curve, params *ECIESParams)

func Encrypt

func Encrypt(rand io.Reader, pub *PublicKey, m, s1, s2 []byte) (ct []byte, err error)

Encrypt encrypts a message using ECIES as specified in SEC 1, 5.1.

s1 and s2 contain shared information that is not part of the resulting ciphertext. s1 is fed into key derivation, s2 is fed into the MAC. If the shared information parameters aren't being used, they should be nil.

func MaxSharedKeyLength

func MaxSharedKeyLength(pub *PublicKey) int

MaxSharedKeyLength returns the maximum length of the shared key the public key can produce.

Types

type ECIESParams

type ECIESParams struct {
	Hash func() hash.Hash // hash function

	Cipher    func([]byte) (cipher.Block, error) // symmetric cipher
	BlockSize int                                // block size of symmetric cipher
	KeyLen    int                                // length of symmetric key
	// contains filtered or unexported fields
}

func ParamsFromCurve

func ParamsFromCurve(curve elliptic.Curve) (params *ECIESParams)

ParamsFromCurve selects parameters optimal for the selected elliptic curve. Only the curves P256, P384, and P512 are supported.

type PrivateKey

type PrivateKey struct {
	PublicKey
	D *big.Int
}

PrivateKey is a representation of an elliptic curve private key.

func GenerateKey

func GenerateKey(rand io.Reader, curve elliptic.Curve, params *ECIESParams) (prv *PrivateKey, err error)

Generate an elliptic curve public / private keypair. If params is nil, the recommended default parameters for the key will be chosen.

func HexKey

func HexKey(prv string) (*PrivateKey, error)

func ImportECDSA

func ImportECDSA(prv *ecdsa.PrivateKey) *PrivateKey

Import an ECDSA private key as an ECIES private key.

func (*PrivateKey) Decrypt

func (prv *PrivateKey) Decrypt(c, s1, s2 []byte) (m []byte, err error)

Decrypt decrypts an ECIES ciphertext.

func (*PrivateKey) EncryptShared

func (prv *PrivateKey) EncryptShared(rand io.Reader, pub *PublicKey, m, s1, s2 []byte) (ct []byte, err error)

func (*PrivateKey) ExportECDSA

func (prv *PrivateKey) ExportECDSA() *ecdsa.PrivateKey

Export an ECIES private key as an ECDSA private key.

func (*PrivateKey) GenerateShared

func (prv *PrivateKey) GenerateShared(pub *PublicKey, skLen, macLen int) (sk []byte, err error)

ECDH key agreement method used to establish secret keys for encryption.

func (*PrivateKey) PrivateKeyHex

func (prv *PrivateKey) PrivateKeyHex() string

func (*PrivateKey) PublicKeyHex

func (prv *PrivateKey) PublicKeyHex() string

type PublicKey

type PublicKey struct {
	X *big.Int
	Y *big.Int
	elliptic.Curve
	Params *ECIESParams
}

PublicKey is a representation of an elliptic curve public key.

func Hex2PublicKey

func Hex2PublicKey(hexkey string) (*PublicKey, error)

func ImportECDSAPublic

func ImportECDSAPublic(pub *ecdsa.PublicKey) *PublicKey

Import an ECDSA public key as an ECIES public key.

func (*PublicKey) ExportECDSA

func (pub *PublicKey) ExportECDSA() *ecdsa.PublicKey

Export an ECIES public key as an ECDSA public key.