crypto

Documentation

Overview

Copyright (c) 2026 Veld Authors. SPDX-License-Identifier: MIT

Copyright (c) 2026 Veld Authors. SPDX-License-Identifier: MIT

Index

• Variables
• func VerifyPeerSig(peerEd25519Public ed25519.PublicKey, ...) error
• type HandshakeResult
• type Identity
  • func Generate() (*Identity, error)
  • func (id *Identity) Fingerprint() string
  • func (id *Identity) SignForPeer(theirX25519Public [32]byte, timestampSec int64) ([64]byte, error)
• type InitiatorHS
  • func NewInitiatorHS(localID *Identity, peerX25519 [32]byte, networkID [16]byte) (*InitiatorHS, error)
  • func (h *InitiatorHS) BuildMessage1(nowSec int64) ([]byte, error)
  • func (h *InitiatorHS) ProcessMessage2(msg []byte, _ int64) (*HandshakeResult, error)
• type PeerLookupFn
• type ResponderHS
  • func NewResponderHS(localID *Identity, peerLookup PeerLookupFn) (*ResponderHS, error)
  • func (h *ResponderHS) BuildMessage2(nowSec int64) ([]byte, *HandshakeResult, error)
  • func (h *ResponderHS) ProcessMessage1(msg []byte, _ int64) error

Variables

var ErrHandshakeDrop = errors.New("handshake dropped")

ErrHandshakeDrop is returned when a handshake message must be silently dropped. The caller MUST NOT send any response — doing so leaks information about valid keys.

Functions

func VerifyPeerSig

func VerifyPeerSig(peerEd25519Public ed25519.PublicKey, peerX25519Public, ourX25519Public [32]byte, sig [64]byte, timestampSec int64) error

VerifyPeerSig verifies the signature a remote peer included in their handshake message. peerEd25519Public: their permanent Ed25519 public key peerX25519Public: their X25519 static key (from handshake) ourX25519Public: our X25519 static key sig: the signature to verify timestampSec: timestamp from the handshake; must be within ±30s of now

Types

type HandshakeResult

type HandshakeResult struct {
	// Initiator: SendCS=cs1, RecvCS=cs2 (Noise IK spec convention)
	// Responder: SendCS=cs2, RecvCS=cs1
	SendCS            *noise.CipherState
	RecvCS            *noise.CipherState
	SessionID         [8]byte
	PeerEd25519Public ed25519.PublicKey
	NetworkID         [16]byte
}

HandshakeResult holds the outputs of a completed Noise IK handshake.

type Identity

type Identity struct {
	Ed25519Private ed25519.PrivateKey // 64 bytes
	Ed25519Public  ed25519.PublicKey  // 32 bytes
	X25519Private  [32]byte           // 32 bytes
	X25519Public   [32]byte           // 32 bytes
	X25519Sig      [64]byte           // Ed25519 sig over X25519Public
}

Identity holds the permanent peer identity.

func Generate

func Generate() (*Identity, error)

Generate creates a fresh Identity with new Ed25519 and X25519 keypairs.

func (*Identity) Fingerprint

func (id *Identity) Fingerprint() string

Fingerprint returns a hex-encoded SHA-256 of the Ed25519 public key.

func (*Identity) SignForPeer

func (id *Identity) SignForPeer(theirX25519Public [32]byte, timestampSec int64) ([64]byte, error)

SignForPeer returns an Ed25519 signature over (ourX25519Public || theirX25519Public || unixTimestampSeconds). Used in the Noise IK handshake payload.

type InitiatorHS

type InitiatorHS struct {
	// contains filtered or unexported fields
}

InitiatorHS is the initiator side of a Noise IK handshake.

func NewInitiatorHS

func NewInitiatorHS(localID *Identity, peerX25519 [32]byte, networkID [16]byte) (*InitiatorHS, error)

NewInitiatorHS creates an initiator-side Noise IK handshake directed at peerX25519.

func (*InitiatorHS) BuildMessage1

func (h *InitiatorHS) BuildMessage1(nowSec int64) ([]byte, error)

BuildMessage1 constructs the initiator's first Noise IK handshake message.

Payload (120 bytes, encrypted by Noise):

ed25519_pub [32]  initiator's Ed25519 public key
sig         [64]  SignForPeer(peerX25519, nowSec)
network_id  [16]  the network UUID
timestamp   [ 8]  nowSec as big-endian uint64

func (*InitiatorHS) ProcessMessage2

func (h *InitiatorHS) ProcessMessage2(msg []byte, _ int64) (*HandshakeResult, error)

ProcessMessage2 decrypts and validates the responder's reply, returning session keys. Returns ErrHandshakeDrop on ANY validation failure — caller must send no response.

Payload (112 bytes, decrypted by Noise):

ed25519_pub [32]  responder's Ed25519 public key
sig         [64]  responder's SignForPeer(initiator_x25519, nowSec)
session_id  [ 8]  random
timestamp   [ 8]  big-endian uint64

type PeerLookupFn

type PeerLookupFn func(ed25519Pub []byte) (x25519Pub [32]byte, known bool)

PeerLookupFn authorizes an initiator by Ed25519 public key. Returns the peer's expected X25519 static pubkey from the peer table. Returns false if the peer is unknown — the caller must silently drop.

type ResponderHS

type ResponderHS struct {
	// contains filtered or unexported fields
}

ResponderHS is the responder side of a Noise IK handshake.

func NewResponderHS

func NewResponderHS(localID *Identity, peerLookup PeerLookupFn) (*ResponderHS, error)

NewResponderHS creates a responder-side Noise IK handshake state. peerLookup is called during ProcessMessage1 to authorize the initiator.

func (*ResponderHS) BuildMessage2

func (h *ResponderHS) BuildMessage2(nowSec int64) ([]byte, *HandshakeResult, error)

BuildMessage2 constructs the responder's reply and returns session keys. Must only be called after a successful ProcessMessage1.

Payload (112 bytes, encrypted by Noise):

ed25519_pub [32]  responder's Ed25519 public key
sig         [64]  SignForPeer(peerX25519, nowSec)
session_id  [ 8]  random
timestamp   [ 8]  nowSec as big-endian uint64

func (*ResponderHS) ProcessMessage1

func (h *ResponderHS) ProcessMessage1(msg []byte, _ int64) error

ProcessMessage1 decrypts and validates the initiator's first message. Returns ErrHandshakeDrop on ANY validation failure — caller must send no response.