ecdh

README

The ECDH key exchange

Elliptic curve Diffie–Hellman (ECDH) is an anonymous key agreement protocol that allows two parties, each having an elliptic curve public–private key pair, to establish a shared secret over an insecure channel.

This package implements a generic interface for ECDH and supports the generic crypto/elliptic and the x/crypto/curve25519 out of the box.

Installation

Install in your GOPATH: go get -u github.com/aead/ecdh

Documentation

Overview

Package ecdh implements the Diffie-Hellman key exchange using elliptic curves (ECDH). It directly provides ECDH implementations for the NIST curves P224, P256, P384, and Bernstein's Cruve25519.

For generic curves this implementation of ECDH only uses the x-coordinate as the computed secret.

Index

• type CurveParams
• type KeyExchange
  • func Generic(c elliptic.Curve) KeyExchange
  • func X25519() KeyExchange
• type Point

Examples

• Generic
• X25519

Types

type CurveParams

type CurveParams struct {
	Name    string // the canonical name of the curve
	BitSize int    // the size of the underlying field
}

CurveParams contains the parameters of an elliptic curve.

type KeyExchange

type KeyExchange interface {
	// GenerateKey generates a private/public key pair using entropy from rand.
	// If rand is nil, crypto/rand.Reader will be used.
	GenerateKey(rand io.Reader) (private crypto.PrivateKey, public crypto.PublicKey, err error)

	// Params returns the curve parameters - like the field size.
	Params() CurveParams

	// PublicKey returns the public key corresponding to the given private one.
	PublicKey(private crypto.PrivateKey) (public crypto.PublicKey)

	// Check returns a non-nil error if the peers public key cannot used for the
	// key exchange - for instance the public key isn't a point on the elliptic curve.
	// It's recommended to check peer's public key before computing the secret.
	Check(peersPublic crypto.PublicKey) (err error)

	// ComputeSecret returns the secret value computed from the given private key
	// and the peers public key.
	ComputeSecret(private crypto.PrivateKey, peersPublic crypto.PublicKey) (secret []byte)
}

KeyExchange is the interface defining all functions necessary for ECDH.

func Generic

func Generic(c elliptic.Curve) KeyExchange

Generic creates a new ecdh.KeyExchange with generic elliptic.Curve implementations.

Example

An example for the ECDH key-exchange using the curve P256.

p256 := Generic(elliptic.P256())

privateAlice, publicAlice, err := p256.GenerateKey(rand.Reader)
if err != nil {
	fmt.Printf("Failed to generate Alice's private/public key pair: %s\n", err)
}
privateBob, publicBob, err := p256.GenerateKey(rand.Reader)
if err != nil {
	fmt.Printf("Failed to generate Bob's private/public key pair: %s\n", err)
}

if err := p256.Check(publicBob); err != nil {
	fmt.Printf("Bob's public key is not on the curve: %s\n", err)
}
secretAlice := p256.ComputeSecret(privateAlice, publicBob)

if err := p256.Check(publicAlice); err != nil {
	fmt.Printf("Alice's public key is not on the curve: %s\n", err)
}
secretBob := p256.ComputeSecret(privateBob, publicAlice)

if !bytes.Equal(secretAlice, secretBob) {
	fmt.Printf("key exchange failed - secret X coordinates not equal\n")
}

func X25519

func X25519() KeyExchange

X25519 creates a new ecdh.KeyExchange with the elliptic curve Curve25519.

Example

An example for the ECDH key-exchange using Curve25519.

c25519 := X25519()

privateAlice, publicAlice, err := c25519.GenerateKey(rand.Reader)
if err != nil {
	fmt.Printf("Failed to generate Alice's private/public key pair: %s\n", err)
}
privateBob, publicBob, err := c25519.GenerateKey(rand.Reader)
if err != nil {
	fmt.Printf("Failed to generate Bob's private/public key pair: %s\n", err)
}

if err := c25519.Check(publicBob); err != nil {
	fmt.Printf("Bob's public key is not on the curve: %s\n", err)
}
secretAlice := c25519.ComputeSecret(privateAlice, publicBob)

if err := c25519.Check(publicAlice); err != nil {
	fmt.Printf("Alice's public key is not on the curve: %s\n", err)
}
secretBob := c25519.ComputeSecret(privateBob, publicAlice)

if !bytes.Equal(secretAlice, secretBob) {
	fmt.Printf("key exchange failed - secret X coordinates not equal\n")
}

type Point

type Point struct {
	X, Y *big.Int
}

Point represents a generic elliptic curve Point with a X and a Y coordinate.