ecies

README

# NOTE

This implementation is direct fork of Kylom's implementation. I claim no authorship over this code apart from some minor modifications.
Please be aware this code **has not yet been reviewed**.

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


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 ImportECDSA(prv *ecdsa.PrivateKey) *PrivateKey
  • func (prv *PrivateKey) Decrypt(c, s1, s2 []byte) (m []byte, err error)
  • func (prv *PrivateKey) ExportECDSA() *ecdsa.PrivateKey
  • func (prv *PrivateKey) GenerateShared(pub *PublicKey, skLen, macLen int) (sk []byte, err error)
• type PublicKey
  • 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")
)

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使用第1节5.1中指定的ECIES对消息进行加密。

s1和s2包含不属于结果的共享信息 密文。s1被输入到键派生中，s2被输入到mac中。如果 未使用共享信息参数，它们应为零。

func MaxSharedKeyLength

func MaxSharedKeyLength(pub *PublicKey) int

MaxSharedKeyLength返回共享密钥的最大长度 可以生成公钥。

Types

type ECIESParams

type ECIESParams struct {
	Hash func() hash.Hash //哈希函数

	Cipher    func([]byte) (cipher.Block, error) //对称加密
	BlockSize int                                //对称密码的块大小
	KeyLen    int                                //对称密钥长度
	// contains filtered or unexported fields
}

func ParamsFromCurve

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

paramsfromcurve为选定的椭圆曲线选择最佳参数。 仅支持曲线P256、P38 4和P512。

type PrivateKey

type PrivateKey struct {
	PublicKey
	D *big.Int
}

private key是椭圆曲线私钥的表示。

func GenerateKey

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

生成椭圆曲线公钥/私钥对。如果参数为零， the recommended default parameters for the key will be chosen.

func ImportECDSA

func ImportECDSA(prv *ecdsa.PrivateKey) *PrivateKey

将ECDSA私钥导入为ECIES私钥。

func (*PrivateKey) Decrypt

func (prv *PrivateKey) Decrypt(c, s1, s2 []byte) (m []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密钥协议方法。

type PublicKey

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

公钥是椭圆曲线公钥的表示形式。

func ImportECDSAPublic

func ImportECDSAPublic(pub *ecdsa.PublicKey) *PublicKey

将ECDSA公钥导入为特定的公钥。

func (*PublicKey) ExportECDSA

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

将ECIES公钥导出为ECDSA公钥。