spake

package module
v0.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 19, 2026 License: MIT Imports: 8 Imported by: 0

README

SPAKE2 (Go)

A minimal and secure Go implementation of the SPAKE2 password-authenticated key exchange (PAKE) protocol using the Ristretto group.

This library allows two parties that share a low-entropy password to securely establish a shared secret and mutually authenticate without revealing the password, even over untrusted networks.


Features

  • SPAKE2 PAKE protocol
  • Ristretto255 group
  • Constant-size messages
  • Mutual authentication via HMAC
  • No password exposure or transmission
  • Designed for networking and cryptographic projects

Package

package spake

Public Types

type Spake
type Spake struct {
    Role bool
}

Represents a single SPAKE2 protocol instance.

  • Role must differ between the two peers:

    • true → initiator
    • false → responder

All cryptographic state is stored internally.


Public API

func (sp *Spake) Start(password []byte) ([]byte, error)

Initializes the SPAKE2 exchange.

Behavior:

  • Generates a fresh ephemeral scalar
  • Derives a password scalar
  • Computes the blinded public point
  • Serializes the protocol message

Parameters:

  • password: shared secret password (raw bytes)

Returns:

  • A 33-byte message to be sent to the peer
  • An error if initialization fails

Usage:

msg, err := sp.Start(password)

func (sp *Spake) Finish(remoteData []byte) ([]byte, error)

Completes the SPAKE2 key exchange.

Behavior:

  • Validates peer message
  • Removes password blinding
  • Derives the shared secret
  • Derives a MAC key via HKDF

Parameters:

  • remoteData: 33-byte message received from the peer

Returns:

  • The raw shared secret bytes
  • An error if validation or computation fails

Usage:

sharedSecret, err := sp.Finish(peerMsg)

func (sp *Spake) GetLetter() []byte

Generates the authentication MAC.

Behavior:

  • Computes an HMAC over the protocol transcript
  • Proves possession of the shared secret

Returns:

  • A 32-byte MAC to send to the peer

Usage:

mac := sp.GetLetter()

func (sp *Spake) CheckLetter(letter []byte) bool

Verifies the peer’s authentication MAC.

Behavior:

  • Recomputes the transcript MAC
  • Performs constant-time comparison

Parameters:

  • letter: MAC received from the peer

Returns:

  • true if authentication succeeds
  • false otherwise

Usage:

ok := sp.CheckLetter(peerMAC)

Utility Functions

func GetRandomPoint() string

Generates a random Ristretto point encoded as base64.

Use cases:

  • Testing
  • Parameter generation
  • Experimental extensions

Usage:

p := spake.GetRandomPoint()

Protocol Flow Example

// Alice
a := &spake.Spake{Role: true}
msgA, _ := a.Start(password)
send(msgA)

// Bob
b := &spake.Spake{Role: false}
msgB, _ := b.Start(password)
send(msgB)

// Alice
secretA, _ := a.Finish(msgB)
macA := a.GetLetter()
send(macA)

// Bob
secretB, _ := b.Finish(msgA)
ok := b.CheckLetter(macA)

Both secretA and secretB are identical if authentication succeeds.


Security Properties

  • Password is never transmitted or derivable
  • Resistant to passive and active network attacks
  • No offline dictionary attacks without protocol interaction
  • Mutual authentication guaranteed
  • Constant-size messages

Cryptographic Details

  • Group: Ristretto255
  • Hash: SHA-256
  • Key Derivation: HKDF-SHA256
  • Authentication: HMAC-SHA256
  • Protocol versioning included in transcript

Intended Use Cases

  • Secure client-server authentication
  • Encrypted tunnels
  • Device pairing
  • Password-based key exchange
  • Cryptographic research and learning

Notes

  • This implementation assumes both peers share the same password
  • Roles must differ between peers
  • One Spake instance must not be reused

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetRandomPoint

func GetRandomPoint() string

GetRandomPoint generates a random Ristretto point and returns it encoded in base64 format, suitable for testing or parameter generation.

Types

type Spake

type Spake struct {
	Role bool
	// contains filtered or unexported fields
}

Spake holds all state required for a SPAKE2 session, including ephemeral scalars, password-derived values, role information, transcript data, and the derived MAC key.

func (*Spake) CheckLetter

func (sp *Spake) CheckLetter(letter []byte) bool

CheckLetter verifies the peer’s authentication MAC against the local transcript and MAC key, confirming mutual authentication.

func (*Spake) Finish

func (sp *Spake) Finish(remoteData []byte) ([]byte, error)

Finish completes the SPAKE2 key exchange by processing the peer's message, removing the password blinding, deriving the shared secret, and generating the MAC key used for authentication.

func (*Spake) GetLetter

func (sp *Spake) GetLetter() []byte

GetLetter computes the authentication MAC over the SPAKE2 transcript using the derived MAC key, proving possession of the shared secret.

func (*Spake) Start

func (sp *Spake) Start(password []byte) ([]byte, error)

Start initializes the SPAKE2 exchange by generating an ephemeral scalar, deriving the password scalar, computing the blinded public point (X), and returning the serialized message to send to the peer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL