dh

README

DH Functions

This package implements the DH functions, as specified in the noise specs.

Built-in Curves

The following curves are supported,

Curve25519

The protocol name is 25519, e.g., Noise_XX_25519_AESGCM_SHA256.

Curve448

The protocol name is 448, e.g., Noise_XX_448_AESGCM_SHA256.

Secp256k1

The protocol name is secp256k1, e.g., Noise_XX_secp256k1_AESGCM_SHA256.

Customized DH function

To create your own DH function, you'll need to implement the interfaces specified in dh.go, which requires a PublicKey interface, a PrivateKey interface and a Curve interface. And you need to register it using Register(Name, Curve).

Check examples/newdh, which implements a dummy DH function for demonstration. Once implemented, it can be used via the protocol name,

// dumb implements the DH interface for DumbCurve.
dh.Register("Dumb", newDumbCurve)

// Now "Dumb" is a valid dh curve name, and it can be used in the protocol name as,
p, _ := babble.NewProtocol("Noise_NN_Dumb_ChaChaPoly_BLAKE2s", "Demo", true)

Documentation

Overview

Package dh implements the DH functions specified in the noise protocol.

It currently supports three curves:

• Curve 448, which uses https://gitlab.com/yawning/x448.git.
• Curve 25519, which uses https://golang.org/x/crypto/curve25519.
• Curve secp256k1, which uses https://github.com/btcsuite/btcd/btcec.

Index

• func Register(s string, new NewCurve)
• func SupportedCurves() string
• type Curve
  • func FromString(s string) (Curve, error)
• type NewCurve
• type PrivateKey
• type PublicKey

Examples

• FromString

Functions

func Register

func Register(s string, new NewCurve)

Register updates the supported curves used in package dh.

func SupportedCurves

func SupportedCurves() string

SupportedCurves gives the names of all the curves registered. If no new curves are registered, it returns a string as "25519, 448, secp256k1", orders not preserved.

Types

type Curve

type Curve interface {
	fmt.Stringer

	// GenerateKeyPair generates a new Diffie-Hellman key pair. It creates a key
	// pair from entropy. If the entropy is not supplied, it will use rand.Read
	// to generate a new private key.
	GenerateKeyPair(entropy []byte) (PrivateKey, error)

	// LoadPrivateKey uses the data provided to create a new private key.
	LoadPrivateKey(data []byte) (PrivateKey, error)

	// LoadPublicKey uses the data provided to create a new public key.
	LoadPublicKey(data []byte) (PublicKey, error)

	// Size returns the DHLEN value.
	Size() int
}

Curve represents DH functions specified in the noise specs.

func FromString

func FromString(s string) (Curve, error)

FromString uses the provided curve name, s, to query a built-in curve.

Example

package main

import (
	"fmt"

	"github.com/yyforyongyu/babble/dh"
)

func main() {
	// use the curve25519
	x25519, _ := dh.FromString("25519")
	fmt.Println(x25519)

	// use the curve448
	x448, _ := dh.FromString("448")
	fmt.Println(x448)

	// use the secp256k1
	secp256k1, _ := dh.FromString("secp256k1")
	fmt.Println(secp256k1)
}

type NewCurve

type NewCurve func() Curve

NewCurve creates an Curve instance.

type PrivateKey

type PrivateKey interface {
	// Bytes turns the underlying bytes array into a slice.
	Bytes() []byte

	// DH performs a Diffie-Hellman calculation between the private key itself
	// and the public key supplied, returns an output sequence of bytes of
	// length DHLEN.
	//
	// Implementations must handle invalid public keys either by returning some
	// output which is purely a function of the public key and does not depend
	// on the private key, or by signaling an error to the caller. The DH
	// function may define more specific rules for handling invalid values.
	DH(pub []byte) ([]byte, error)

	// Update updates both the private key bytes and the public key bytes with
	// the data supplied. This means the calculation of the public key from the
	// private key shall be implemented inside this method.
	Update(data []byte)

	// PubKey returns the associated public key.
	PubKey() PublicKey
}

PrivateKey is a key pair. Since a private key always corresponds to at least one public key, it makes sense to pair with it inside the struct.

type PublicKey

type PublicKey interface {
	// Bytes turns the underlying bytes array into a slice.
	Bytes() []byte

	// Hex returns the hexstring of the public key.
	Hex() string

	// LoadBytes loads the byte slice into a byte array specifically for a
	// public key defined in each curve.
	LoadBytes(data []byte) error
}

PublicKey represents a public key. The only place to use it is during a DHKE, a public key struct is passed into the DH function.