ecies

package
v0.6.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 7, 2019 License: GPL-3.0, BSD-3-Clause Imports: 14 Imported by: 0

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

Constants

This section is empty.

Variables

View Source 
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")
	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")
	ErrUnsupportedECIESParameters = fmt.Errorf("ecies: unsupported ECIES parameters")
)

Errors returned by the package

View Source 
var (
	// Aes128Sha256Params using AES128 and HMAC-SHA-256-16
	Aes128Sha256Params = &Params{
		NewHash:   sha256.New,
		hashAlgo:  crypto.SHA256,
		NewCipher: aes.NewCipher,
		BlockSize: aes.BlockSize,
		KeyLen:    16,
	}

	// Aes256Sha256Params using AES256 and HMAC-SHA-256-32
	Aes256Sha256Params = &Params{
		NewHash:   sha256.New,
		hashAlgo:  crypto.SHA256,
		NewCipher: aes.NewCipher,
		BlockSize: aes.BlockSize,
		KeyLen:    32,
	}

	// Aes256Sha384Params using AES256 and HMAC-SHA-384-48
	Aes256Sha384Params = &Params{
		NewHash:   sha512.New384,
		hashAlgo:  crypto.SHA384,
		NewCipher: aes.NewCipher,
		BlockSize: aes.BlockSize,
		KeyLen:    32,
	}

	// Aes256Sha512Params using AES256 and HMAC-SHA-512-64
	Aes256Sha512Params = &Params{
		NewHash:   sha512.New,
		hashAlgo:  crypto.SHA512,
		NewCipher: aes.NewCipher,
		BlockSize: aes.BlockSize,
		KeyLen:    32,
	}

	// DefaultParams holds default parameters for the default curve
	DefaultParams = ParamsFromCurve(DefaultCurve)
)
View Source 
var (
	// DefaultCurve is an instance of the secp256k1 curve
	DefaultCurve = ethcrypto.S256()
)

Functions

func Encrypt 

func Encrypt(rand io.Reader, pub *ecdsa.PublicKey, msg, 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 MarshalPublicKey 

func MarshalPublicKey(k *ecdsa.PublicKey) []byte

MarshalPublicKey converts public key into the uncompressed form specified in section 4.3.6 of ANSI X9.62.

func UnmarshalPublicKey 

func UnmarshalPublicKey(curve elliptic.Curve, b []byte, k *ecdsa.PublicKey) error

UnmarshalPublicKey converts a point, serialized by MarshalPublicKey, into a public key. It is an error if the point is not in uncompressed form or is not on the curve.

Types

type CipherText 

type CipherText struct {
	EphemeralPublicKey *ecdsa.PublicKey
	*EncryptedAuthenticatedMessage
}

CipherText holds parts of encrypted message

func (*CipherText) Marshal 

func (ct *CipherText) Marshal() ([]byte, error)

Marshal converts parts of encrypted message into byte slice.

func (*CipherText) Unmarshal 

func (ct *CipherText) Unmarshal(b []byte, curve elliptic.Curve, hashSize int) error

Unmarshal splits the bytes of encrypted message, serialized by Marshal, into the parts of encrypted message.

type ECIES 

type ECIES struct {
	// contains filtered or unexported fields
}

ECIES implements Elliptic Curve Integrated Encryption Scheme

func Must 

func Must(e *ECIES, err error) *ECIES

Must is a helper that wraps a call to a function returning (*ECIES, error) and panics if the error is non-nil. It is intended for use in variable initializations such as 

var e = ecies.Must(ecies.NewGenerate(ecies.DefaultCurve, rand.Reader))

func New 

func New(prv *ecdsa.PrivateKey) (*ECIES, error)

New creates an instance of ECIES from specified private key, it tries automatically select appropriate parameters for encryption scheme.

func NewGenerate 

func NewGenerate(c elliptic.Curve, rand io.Reader) (*ECIES, error)

NewGenerate creates an instance of ECIES by generating a public and private key pair for specified elliptic curve, and selecting default parameters for encryption scheme.

func NewWithParams 

func NewWithParams(prv *ecdsa.PrivateKey, params *Params) (*ECIES, error)

NewWithParams creates an instance of ECIES from specified private key and params. If params is nil, the recommended default parameters for the encryption scheme will be chosen.

func (*ECIES) Decrypt 

func (ci *ECIES) Decrypt(ct, s1, s2 []byte) (msg []byte, err error)

Decrypt decrypts an ECIES ciphertext.

func (*ECIES) DeriveSecretKeyringMaterial 

func (ci *ECIES) DeriveSecretKeyringMaterial(pub *ecdsa.PublicKey, s1 []byte) (skm *SecretKeyringMaterial, err error)

DeriveSecretKeyringMaterial derives secret keyring material by computing shared secret from private and public keys and passing it as a parameter to the KDF.

func (*ECIES) Encrypt 

func (ci *ECIES) Encrypt(rand io.Reader, pub *ecdsa.PublicKey, msg, 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 (*ECIES) EncryptToCipherText 

func (ci *ECIES) EncryptToCipherText(rand io.Reader, pub *ecdsa.PublicKey, msg, s1, s2 []byte) (ct *CipherText, err error)

EncryptToCipherText encrypts a message using ECIES as specified in SEC 1, 5.1. Instead of bytes it returns all the parts of encrypted message.

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 (*ECIES) GenerateShared 

func (ci *ECIES) GenerateShared(pub *ecdsa.PublicKey, skLen, macLen int) (sk []byte, err error)

GenerateShared generates shared secret keys for encryption using ECDH key agreement protocol.

func (*ECIES) MaxSharedKeyLength 

func (ci *ECIES) MaxSharedKeyLength() int

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

func (*ECIES) Params 

func (ci *ECIES) Params() *Params

Params returns the parameters of selected encryption scheme.

func (*ECIES) PrivateKey 

func (ci *ECIES) PrivateKey() *ecdsa.PrivateKey

PrivateKey returns pointer to the internal private key.

func (*ECIES) PublicKey 

func (ci *ECIES) PublicKey() *ecdsa.PublicKey

PublicKey returns pointer to the internal public key.

type EncryptedAuthenticatedMessage 

type EncryptedAuthenticatedMessage struct {
	EncryptedMessage []byte
	HMAC             []byte
}

EncryptedAuthenticatedMessage holds the encrypted message and HMAC

type NewCipherFun 

type NewCipherFun func([]byte) (cipher.Block, error)

NewCipherFun is a function type that creates and returns a new cipher.Block The key argument should be the AES key, either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256.

type NewHashFun 

type NewHashFun func() hash.Hash

NewHashFun is a function type that returns a new hash.Hash computing the checksum.

type Params 

type Params struct {
	NewHash NewHashFun // hash function

	NewCipher NewCipherFun // symmetric cipher
	BlockSize int          // block size of symmetric cipher
	KeyLen    int          // length of symmetric key
	// contains filtered or unexported fields
}

Params holds all the parameters of selected encryption scheme

func ParamsFromCurve 

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

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

func (*Params) DecryptAuth 

func (p *Params) DecryptAuth(skm *SecretKeyringMaterial, eam *EncryptedAuthenticatedMessage, s2 []byte) (msg []byte, err error)

DecryptAuth checks encrypted message HMAC and if it's valid decrypts the message s2 contains shared information that is not part of the ciphertext, it's fed into the MAC. If the shared information parameters aren't being used, they should be nil.

func (*Params) EncryptAuth 

func (p *Params) EncryptAuth(rand io.Reader, skm *SecretKeyringMaterial, msg, s2 []byte) (eam *EncryptedAuthenticatedMessage, err error)

EncryptAuth encrypts message using provided secret keyring material and returns encrypted message with the HMAC s2 contains shared information that is not part of the resulting ciphertext, it's fed into the MAC. If the shared information parameters aren't being used, they should be nil.

type SecretKeyringMaterial 

type SecretKeyringMaterial struct {
	EncryptionKey []byte
	MACKey        []byte
}

SecretKeyringMaterial hold the encryption key and MAC key

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.