eciesgo

README

eciesgo

Elliptic Curve Integrated Encryption Scheme for secp256k1, written in Go with minimal dependencies.

This is the Go version of ecies/py with a built-in class-like secp256k1 API, you may go there for detailed documentation of the mechanism under the hood.

Install

go get github.com/ecies/go/v2

Go 1.13 is required cause fmt.Errorf is used to wrap errors.

⚠️ Please use version 2.0.3 and later. It's much faster and safer.

Quick Start

package main

import (
	ecies "github.com/ecies/go/v2"
	"log"
)

func main() {
	k, err := ecies.GenerateKey()
	if err != nil {
		panic(err)
	}
	log.Println("key pair has been generated")

	ciphertext, err := ecies.Encrypt(k.PublicKey, []byte("THIS IS THE TEST"))
	if err != nil {
		panic(err)
	}
	log.Printf("plaintext encrypted: %v\n", ciphertext)

	plaintext, err := ecies.Decrypt(k, ciphertext)
	if err != nil {
		panic(err)
	}
	log.Printf("ciphertext decrypted: %s\n", string(plaintext))
}

Benchmarks

With CGO:

goos: linux
goarch: amd64
pkg: github.com/ecies/go/v2
cpu: AMD Ryzen 7 5700G with Radeon Graphics         
BenchmarkEncrypt-16        12250             98122 ns/op            5185 B/op         61 allocs/op
BenchmarkDecrypt-16        23934             50046 ns/op            4097 B/op         46 allocs/op

Without CGO:

goos: linux
goarch: amd64
pkg: github.com/ecies/go/v2
cpu: AMD Ryzen 7 5700G with Radeon Graphics         
BenchmarkEncrypt-16        10000            112632 ns/op            5655 B/op         68 allocs/op
BenchmarkDecrypt-16        14038             85641 ns/op            4725 B/op         56 allocs/op

Documentation

Index

• func Decrypt(privkey *PrivateKey, msg []byte) ([]byte, error)
• func Encrypt(pubkey *PublicKey, msg []byte) ([]byte, error)
• type PrivateKey
  • func GenerateKey() (*PrivateKey, error)
  • func NewPrivateKeyFromBytes(priv []byte) *PrivateKey
  • func NewPrivateKeyFromHex(s string) (*PrivateKey, error)
  • func (k *PrivateKey) Bytes() []byte
  • func (k *PrivateKey) ECDH(pub *PublicKey) ([]byte, error)
  • func (k *PrivateKey) Encapsulate(pub *PublicKey) ([]byte, error)
  • func (k *PrivateKey) Equals(priv *PrivateKey) bool
  • func (k *PrivateKey) Hex() string
• type PublicKey
  • func NewPublicKeyFromBytes(b []byte) (*PublicKey, error)
  • func NewPublicKeyFromHex(s string) (*PublicKey, error)
  • func (k *PublicKey) Bytes(compressed bool) []byte
  • func (k *PublicKey) Decapsulate(priv *PrivateKey) ([]byte, error)
  • func (k *PublicKey) Equals(pub *PublicKey) bool
  • func (k *PublicKey) Hex(compressed bool) string

Functions

func Decrypt

func Decrypt(privkey *PrivateKey, msg []byte) ([]byte, error)

Decrypt decrypts a passed message with a receiver private key, returns plaintext or decryption error

func Encrypt

func Encrypt(pubkey *PublicKey, msg []byte) ([]byte, error)

Encrypt encrypts a passed message with a receiver public key, returns ciphertext or encryption error

Types

type PrivateKey

type PrivateKey struct {
	*PublicKey
	D *big.Int
}

PrivateKey is an instance of secp256k1 private key with nested public key

func GenerateKey

func GenerateKey() (*PrivateKey, error)

GenerateKey generates secp256k1 key pair

func NewPrivateKeyFromBytes

func NewPrivateKeyFromBytes(priv []byte) *PrivateKey

NewPrivateKeyFromBytes decodes private key raw bytes, computes public key and returns PrivateKey instance

func NewPrivateKeyFromHex

func NewPrivateKeyFromHex(s string) (*PrivateKey, error)

NewPrivateKeyFromHex decodes hex form of private key raw bytes, computes public key and returns PrivateKey instance

func (*PrivateKey) Bytes

func (k *PrivateKey) Bytes() []byte

Bytes returns private key raw bytes

func (*PrivateKey) ECDH

func (k *PrivateKey) ECDH(pub *PublicKey) ([]byte, error)

ECDH derives shared secret; Must not be used as encryption key, it increases chances to perform successful key restoration attack

func (*PrivateKey) Encapsulate

func (k *PrivateKey) Encapsulate(pub *PublicKey) ([]byte, error)

Encapsulate encapsulates key by using Key Encapsulation Mechanism and returns symmetric key; can be safely used as encryption key

func (*PrivateKey) Equals

func (k *PrivateKey) Equals(priv *PrivateKey) bool

Equals compares two private keys with constant time (to resist timing attacks)

func (*PrivateKey) Hex

func (k *PrivateKey) Hex() string

Hex returns private key bytes in hex form

type PublicKey

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

PublicKey instance with nested elliptic.Curve interface (secp256k1 instance in our case)

func NewPublicKeyFromBytes

func NewPublicKeyFromBytes(b []byte) (*PublicKey, error)

NewPublicKeyFromBytes decodes public key raw bytes and returns PublicKey instance; Supports both compressed and uncompressed public keys

func NewPublicKeyFromHex

func NewPublicKeyFromHex(s string) (*PublicKey, error)

NewPublicKeyFromHex decodes hex form of public key raw bytes and returns PublicKey instance

func (*PublicKey) Bytes

func (k *PublicKey) Bytes(compressed bool) []byte

Bytes returns public key raw bytes; Could be optionally compressed by dropping Y part

func (*PublicKey) Decapsulate

func (k *PublicKey) Decapsulate(priv *PrivateKey) ([]byte, error)

Decapsulate decapsulates key by using Key Encapsulation Mechanism and returns symmetric key; can be safely used as encryption key

func (*PublicKey) Equals

func (k *PublicKey) Equals(pub *PublicKey) bool

Equals compares two public keys with constant time (to resist timing attacks)

func (*PublicKey) Hex

func (k *PublicKey) Hex(compressed bool) string

Hex returns public key bytes in hex form