ecc

README

Elliptic Curve Cryptography

ECC is a Golang package which provides a uniform API for using Elliptic curves with one single key pair, instead of having to use specific libraries with different key structs e.g. ECDSA's key. Supporting any elliptic.curve with easy capabilities to switch it out. Even P521 is supported! I won't even comment on the struggles of that one.

Features

• ECDSA (Elliptic curve digital signature algorithm)
• ECIES (Elliptic curve integrated encryption scheme)
• Mutlicurve support (unlike many other libs we support any elliptic.Curve)
• Single EC key rather than separate per curve or lib

Todo

• Implement more curves
  • Curve25519
  • K-233
  • M-383

Examples

Encrypt using AES256 GCM HKDF-SHA256 to a public key then decrypt it using the private key:

package main

import (
	"bytes"
	"crypto/elliptic"
	"fmt"
	"log"

	"github.com/1william1/ecc"
)

func main() {
	k1, err := ecc.GenerateKey(elliptic.P256())
	if err != nil {
		log.Fatalln(err)
	}

	msg := "Test must have worked"
	c, err := k1.Public.Encrypt([]byte(msg))
	if err != nil {
		log.Fatalln(err)
	}

	m, err := k1.Decrypt(c, k1.Public.Curve)
	if err != nil {
		log.Fatalln(err)
	}

	if !bytes.Equal([]byte(msg), m) {
		log.Fatalln("messages do not match")
	}

	fmt.Printf("Cipher text: %x\n", c)
	fmt.Printf("Plain text: %s\n", string(m))
}

Documentation

Index

• Constants
• Variables
• func HKDFSHA256(secret []byte) (key []byte, err error)
• type EncryptOption
  • func NewOptionKDF(kdf func(secret []byte) ([]byte, error)) *EncryptOption
• type OperationMode
• type OptionProperty
• type Private
  • func GenerateKey(curve elliptic.Curve) (*Private, error)
  • func (private *Private) Decrypt(m []byte, curve elliptic.Curve, options ...*EncryptOption) ([]byte, error)
  • func (private *Private) Sign(digest []byte) (r *big.Int, s *big.Int, err error)
  • func (private *Private) SignToASN1(digest []byte) ([]byte, error)
  • func (private *Private) ToECDSA() *ecdsa.PrivateKey
• type Public
  • func ParsePublicKey(curve elliptic.Curve, rawBytes []byte) (*Public, error)
  • func (public *Public) Bytes() []byte
  • func (public *Public) Encrypt(message []byte, options ...*EncryptOption) ([]byte, error)
  • func (public *Public) Equal(key *Public) bool
  • func (public *Public) Fingerprint(Hash ...hash.Hash) []byte
  • func (public *Public) ToECDSA() *ecdsa.PublicKey
  • func (public *Public) Verify(digest []byte, r *big.Int, s *big.Int) bool
  • func (public *Public) VerifyASN1(digest []byte, signature []byte) bool

Constants

const (
	//OperationModeGCM will set the cipher operation mode to GCM
	OperationModeGCM OperationMode = 0
	//OperationModeCBC will set the cipher operation mode to CBC
	OperationModeCBC OperationMode = 1

	//PropertyOperationMode sets the cipher operation mode
	PropertyOperationMode OptionProperty = 1
	//PropertyKDF allows you to set a custom KDF
	PropertyKDF OptionProperty = 2
)

const (
	//VERSION uses semantic versioning
	VERSION = "v1.0.1"
)

Variables

var (
	//OptionAESGCM will set the operation mode as GCM
	OptionAESGCM EncryptOption = EncryptOption{1, OperationModeGCM}

	//ErrUnknownOption is returned when a unknown EncryptionOption is provided
	ErrUnknownOption = errors.New("ecc/ecies: unknown encryption option")
	//ErrUnexpectedOptionDataType is returned when a unexpected datatype is used for the EncryptionOption.Value
	ErrUnexpectedOptionDataType = errors.New("ecc/ecies: unexpected option value data type")
)

var (

	//RandReader is a cryptographic random number generator default is crypto/rand
	RandReader io.Reader = rand.Reader

	//ErrTooShort is returned when the input is shorter than a real possible ciphertext
	ErrTooShort = errors.New("ecc/ecies: invalid ciphertext, too short")

	//ErrWrongKeyLength is returned when parsing a public or private key when the input length does not match the expected length based on the curve
	ErrWrongKeyLength = errors.New("ecc/key: could not parse key, wrong length")
)

Functions

func HKDFSHA256

func HKDFSHA256(secret []byte) (key []byte, err error)

HKDFSHA256 generates a secure key from a secret using hkdf and sha256

Types

type EncryptOption

type EncryptOption struct {
	Property OptionProperty
	Value    interface{}
}

EncryptOption allows you set set options such as the KDF and cipher

func NewOptionKDF

func NewOptionKDF(kdf func(secret []byte) ([]byte, error)) *EncryptOption

NewOptionKDF allows you so set a custom KDF when encrypting and decryting

type OperationMode

type OperationMode uint8

OperationMode sets which operation mode to use

type OptionProperty

type OptionProperty uint8

OptionProperty is used as the "property" in a EncryptionOption

type Private

type Private struct {
	//D is the private part of the elliptic curve and acts as the key
	D *big.Int

	Public *Public
}

Private represents a elliptic curve private key

func GenerateKey

func GenerateKey(curve elliptic.Curve) (*Private, error)

GenerateKey generates a new elliptic curve key pair

func (*Private) Decrypt

func (private *Private) Decrypt(m []byte, curve elliptic.Curve, options ...*EncryptOption) ([]byte, error)

Decrypt will decrypt a ECIES message

func (*Private) Sign

func (private *Private) Sign(digest []byte) (r *big.Int, s *big.Int, err error)

Sign will perform a ECDSA

func (*Private) SignToASN1

func (private *Private) SignToASN1(digest []byte) ([]byte, error)

SignToASN1 will perform a ECDSA and encoded to using ASN1

func (*Private) ToECDSA

func (private *Private) ToECDSA() *ecdsa.PrivateKey

ToECDSA will convert the private key into a ECDSA compatable private key

type Public

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

Public is a public elliptic curve key

func ParsePublicKey

func ParsePublicKey(curve elliptic.Curve, rawBytes []byte) (*Public, error)

ParsePublicKey takes in a array of bytes containing the public key

This implements a parser for the public.Bytes() method's format

func (*Public) Bytes

func (public *Public) Bytes() []byte

Bytes returns the public key in raw bytes

Bytes() acts similarly to elliptic.Marshal()

byte{4} | x | y x and y are equal in length and can be split in half to extract each cordinate when popping index 0.

func (*Public) Encrypt

func (public *Public) Encrypt(message []byte, options ...*EncryptOption) ([]byte, error)

Encrypt uses ECIES to encrypt a message to the given public key

AES256 (depending on the KDF) GCM

func (*Public) Equal

func (public *Public) Equal(key *Public) bool

Equal securely comparses two public keys in constant time to minigate timing attacks.

func (*Public) Fingerprint

func (public *Public) Fingerprint(Hash ...hash.Hash) []byte

Fingerprint returns a hash digest of X | Y

Custom hash algorithm example:

public.Fingerprint(sha256.New())

func (*Public) ToECDSA

func (public *Public) ToECDSA() *ecdsa.PublicKey

ToECDSA will convert the public key into a ECDSA compatable public key

func (*Public) Verify

func (public *Public) Verify(digest []byte, r *big.Int, s *big.Int) bool

Verify will verify the digest was signed from this key

func (*Public) VerifyASN1

func (public *Public) VerifyASN1(digest []byte, signature []byte) bool

VerifyASN1 will verify this ASN1 encoded signature was signed from this key

Digest is the output hash from the input of the signature