x25519

Documentation

Overview

Package x25519 provides Diffie-Hellman functions as specified in RFC-7748.

Validation of public keys.

The Diffie-Hellman function, as described in RFC-7748 [1], works for any public key. However, if a different protocol requires contributory behaviour [2,3], then the public keys must be validated against low-order points [3,4]. To do that, the Shared function performs this validation internally and returns false when the public key is invalid (i.e., it is a low-order point).

References:

• [1] RFC7748 by Langley, Hamburg, Turner (https://rfc-editor.org/rfc/rfc7748.txt)
• [2] Curve25519 by Bernstein (https://cr.yp.to/ecdh.html)
• [3] Bernstein (https://cr.yp.to/ecdh.html#validate)
• [4] Cremers&Jackson (https://eprint.iacr.org/2019/526)

Example (X25519)

var AliceSecret, BobSecret,
	AlicePublic, BobPublic,
	AliceShared, BobShared Key

// Generating Alice's secret and public keys
_, _ = io.ReadFull(rand.Reader, AliceSecret[:])
KeyGen(&AlicePublic, &AliceSecret)

// Generating Bob's secret and public keys
_, _ = io.ReadFull(rand.Reader, BobSecret[:])
KeyGen(&BobPublic, &BobSecret)

// Deriving Alice's shared key
okA := Shared(&AliceShared, &AliceSecret, &BobPublic)

// Deriving Bob's shared key
okB := Shared(&BobShared, &BobSecret, &AlicePublic)

fmt.Println(AliceShared == BobShared && okA && okB)

Output:

true

Index

• Constants
• func KeyGen(public, secret *Key)
• func Shared(shared, secret, public *Key) bool
• type Key

Examples

• Package (X25519)

Constants

const Size = 32

Size is the length in bytes of a X25519 key.

Functions

func KeyGen

func KeyGen(public, secret *Key)

KeyGen obtains a public key given a secret key.

func Shared

func Shared(shared, secret, public *Key) bool

Shared calculates Alice's shared key from Alice's secret key and Bob's public key returning true on success. A failure case happens when the public key is a low-order point, thus the shared key is all-zeros and the function returns false.

Types

type Key

type Key [Size]byte

Key represents a X25519 key.