x25519

Documentation

Overview

Package x25519 provides an implementation of the X25519 function, which performs scalar multiplication on the elliptic curve known as Curve25519. See RFC 7748.

Example

Example demonstrates common operations.

// Basic operations are API compatible with x/crypto/curve25519.

// Key generation
alicePrivate := make([]byte, ScalarSize)
if _, err := rand.Read(alicePrivate); err != nil {
	panic("rand.Read: " + err.Error())
}

alicePublic, err := X25519(alicePrivate, Basepoint)
if err != nil {
	panic("x25519.X25519(Basepoint): " + err.Error())
}

var bobPrivate, bobPublic [32]byte
if _, err := rand.Read(bobPrivate[:]); err != nil {
	panic("rand.Read: " + err.Error())
}
ScalarBaseMult(&bobPublic, &bobPrivate)

// Shared secret
//
// Note: If the "all zero output" check for contributory behavior
// is not wanted, then the "deprecated" ScalarMult call should be
// used.  Marking a routine that still has useful behavior as
// deprecated isn't great, but that is what x/crypto/curve25519 does.
aliceShared, err := X25519(alicePrivate, bobPublic[:])
if err != nil {
	panic("x25519.X25519: " + err.Error())
}

var bobShared, tmp [32]byte
copy(tmp[:], alicePublic)
ScalarMult(&bobShared, &bobPrivate, &tmp) //nolint: staticcheck

if !bytes.Equal(aliceShared, bobShared[:]) {
	panic("shared secret mismatch")
}

fmt.Println("ok")

Output:

ok

Index

• Constants
• Variables
• func EdPrivateKeyToX25519(privateKey ed25519.PrivateKey) []byte
• func EdPublicKeyToX25519(publicKey ed25519.PublicKey) ([]byte, bool)
• func GenerateKey(rand io.Reader) (*PublicKey, *PrivateKey, error)
• func ScalarBaseMult(dst, in *[32]byte)
• func ScalarMult(dst, in, base *[32]byte)
• func X25519(scalar, point []byte) ([]byte, error)
• type PrivateKey
  • func GeneratePrivateKey(rand io.Reader) (*PrivateKey, error)
  • func (priv *PrivateKey) DiffieHellman(pub *PublicKey) *SharedSecret
  • func (priv *PrivateKey) Public() *PublicKey
• type PublicKey
• type SharedSecret
  • func (ss *SharedSecret) IsZero() bool

Examples

• Package

Constants

const (
	// ScalarSize is the size, in bytes, of the scalar input to X25519.
	ScalarSize = 32

	// PointSize is the size, in bytes, of the point input to X25519.
	PointSize = 32

	// PrivateKeySize is the size, in bytes, of private keys as used in this package.
	PrivateKeySize = ScalarSize

	// PublicKeySize is the size, in bytes, of public keys as used in this package.
	PublicKeySize = PointSize

	// SharedSecretSize is the size, in bytes, of shared secrets generated by this package.
	SharedSecretSize = PointSize
)

Variables

var Basepoint []byte

Basepoint is the canonical Curve25519 generator.

Functions

func EdPrivateKeyToX25519

func EdPrivateKeyToX25519(privateKey ed25519.PrivateKey) []byte

EdPrivateKeyToX25519 converts an Ed25519 private key into a corresponding X25519 private key such that the resulting X25519 public key will equal the result from EdPublicKeyToX25519.

func EdPublicKeyToX25519

func EdPublicKeyToX25519(publicKey ed25519.PublicKey) ([]byte, bool)

EdPublicKeyToX25519 converts an Ed25519 public key into the X25519 public key that would be generated from the same private key.

func GenerateKey

func GenerateKey(rand io.Reader) (*PublicKey, *PrivateKey, error)

GenerateKey generates a public/private key pair using entropy from rand. If rand is nil, crypto/rand.Reader will be used.

func ScalarBaseMult

func ScalarBaseMult(dst, in *[32]byte)

ScalarBaseMult sets dst to the product in*base where dst and base are the x coordinates of group points, base is the standard generator and all values are in little-endian form.

It is recommended to use the X25519 function with Basepoint instead, as copying into fixed size arrays can lead to unexpected bugs.

func ScalarMult

func ScalarMult(dst, in, base *[32]byte)

ScalarMult sets dst to the product in*base where dst and base are the x coordinates of group points and all values are in little-endian form.

Deprecated: when provided a low-order point, ScalarMult will set dst to all zeroes, irrespective of the scalar. Instead, use the X25519 function, which will return an error.

func X25519

func X25519(scalar, point []byte) ([]byte, error)

X25519 returns the result of the scalar multiplication (scalar * point), according to RFC 7748, Section 5. scalar, point and the return value are slices of 32 bytes.

scalar can be generated at random, for example with crypto/rand. point should be either Basepoint or the output of another X25519 call.

If point is Basepoint (but not if it's a different slice with the same contents) a precomputed implementation might be used for performance.

Types

type PrivateKey

type PrivateKey [PrivateKeySize]byte

PrivateKey is the type of X25519 private keys.

func GeneratePrivateKey

func GeneratePrivateKey(rand io.Reader) (*PrivateKey, error)

GeneratePrivateKey generates a private key using entropy from rand. If rand is nil, crypto/rand.Reader will be used.

func (*PrivateKey) DiffieHellman

func (priv *PrivateKey) DiffieHellman(pub *PublicKey) *SharedSecret

DiffieHellman performs a Diffie-Hellman key exchange between the private key and the given public key to produce a shared secret.

When provided a low-order public key, Diffe-Hellman key exchange will return a secret containing only zeroes, irrespective of the private key. Handle this case appropriately, if needed.

func (*PrivateKey) Public

func (priv *PrivateKey) Public() *PublicKey

Public returns the public key corresponding to the private key.

type PublicKey

type PublicKey [PublicKeySize]byte

PublicKey is the type of X25519 public keys.

type SharedSecret

type SharedSecret [SharedSecretSize]byte

SharedSecret is the type of the result of a Diffie-Hellman key exchange.

func (*SharedSecret) IsZero

func (ss *SharedSecret) IsZero() bool

IsZero returns true iff the shared secret is the all-zero value.

Comparison is performed without leaking extra information about the secret.