kolo docsbeta

kolo-secure

An encrypted, authenticated channel between two Kolo peers, bound to their kolo-id keys.

On this page

kolo-transport encrypts a QUIC connection with TLS 1.3 but does not say who is on the other side. kolo-secure adds that: after the QUIC handshake, each peer signs a value from the connection's TLS exporter (RFC 9846, section 7.5), the channel binding of RFC 9266, with its kolo-id key under Ed25519ctx (RFC 8032), and a connection is returned only after the peer's signature checks out. It adds identity only; it does not decide which keys to trust.

All steps

The handshake

TLS 1.3 protects the bytes; the three short messages prove who holds each end.

  1. The dialer opens a QUIC connection with TLS 1.3. The certificate is a throwaway key, not the peer's identity: TLS alone proves nothing about who is on the other side.
  2. Both sides derive the same 32-byte value from the TLS session (an exporter). Someone relaying in the middle would get two different values.
  3. On a first stream the dialer sends Hello with its kolo-id public key.
  4. The listener answers Proof: its public key and an Ed25519ctx signature over the exporter value and both keys.
  5. The dialer checks the key it expected and the signature, then sends Finish, its own signature. The listener checks it before it accepts the connection.
  6. Protected: content and integrity, and both keys. Not hidden: IP addresses, ports, sizes, timing, and the keys from anyone who connects.

Install

go get github.com/ciranda-dev/kolo-secure

Builds without cgo.

Quick start

Two fresh identities on 127.0.0.1. The dialer requires the listener's public key, and the listener echoes a stream back.

main.go
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	kolosecure "github.com/ciranda-dev/kolo-secure"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	server, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	client, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}

	l, err := kolosecure.Listen(ctx, "127.0.0.1:0", server, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer l.Close()
	go func() {
		c, err := l.Accept(ctx)
		if err != nil {
			return
		}
		fmt.Printf("dialer is %x\n", c.RemotePublicKey())
		s, err := c.AcceptStream(ctx)
		if err != nil {
			return
		}
		io.Copy(s, s)
		s.Close()
	}()

	c, err := kolosecure.Dial(ctx, l.Addr().String(), client, server.PublicKey(), nil)
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()
	s, err := c.OpenStream(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := s.Write([]byte("hello kolo")); err != nil {
		log.Fatal(err)
	}
	s.Close()
	reply, err := io.ReadAll(s)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", reply)
}

It prints the dialer's public key in hex and hello kolo. A real node loads its identity with koloid.Load and learns the key of the peer it dials from wherever it learned the address.

API reference

The API reference is generated from the Go source and is in English.

Package kolosecure · github.com/ciranda-dev/kolo-secure · v0.1.0

Package kolosecure authenticates a kolo-transport connection with the kolo-id identities of both peers.

After the QUIC handshake, each side signs the connection's TLS exporter value (RFC 9846 section 7.5), its role and both public keys with its kolo-id key, and checks the peer's signature. A connection is returned only once the peer has proved it holds its key on this very connection, so a proof cannot be replayed on another connection, reflected, or relayed by a man in the middle.

Experimental: the API may change before v1.0.0.

Variables

var (
	// ErrInvalidConfig means a Config field is out of range.
	ErrInvalidConfig = errors.New("kolosecure: invalid config")
	// ErrInvalidArgument means a nil or zero identity, a nil transport listener, a bad remote key, or an address kolo-transport refuses.
	ErrInvalidArgument = errors.New("kolosecure: invalid argument")
	// ErrClosed means the listener is closed.
	ErrClosed = errors.New("kolosecure: closed")
	// ErrProtocol means a handshake message was malformed, truncated, too large or unexpected.
	ErrProtocol = errors.New("kolosecure: invalid handshake message")
	// ErrUnsupportedVersion means the peer speaks another handshake version.
	ErrUnsupportedVersion = errors.New("kolosecure: unsupported handshake version")
	// ErrUnexpectedPeer means the peer key is not the expected one, or is the local key.
	ErrUnexpectedPeer = errors.New("kolosecure: unexpected peer key")
	// ErrAuthentication means the peer's proof did not verify, or its key cannot be authenticated.
	ErrAuthentication = errors.New("kolosecure: peer authentication failed")
	// ErrTimeout means the handshake took longer than HandshakeTimeout.
	ErrTimeout = errors.New("kolosecure: handshake timeout")
)

Types

type Config

type Config struct {
	// Transport is passed to kolotransport.Listen or kolotransport.Dial; nil means its defaults. It must be nil for NewListener.
	Transport *kolotransport.Config
	// HandshakeTimeout bounds the kolo-secure handshake after the QUIC handshake. Default 10s, from 1s to 60s.
	HandshakeTimeout time.Duration
	// MaxPending caps the connections of a Listener that are handshaking or waiting for Accept. Listener only. Default 64, from 1 to 1000.
	MaxPending int
}

Config sets the limits of a Listener or a Dial. A zero field takes its default.

type Conn

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

Conn is a connection whose peer has proved it holds RemotePublicKey.

func Dial
func Dial(ctx context.Context, addr string, id *koloid.Identity, remote ed25519.PublicKey, cfg *Config) (*Conn, error)

Dial connects to addr as id and returns once the listener has proved it holds remote. The listener checks the dialer's proof after Dial returns; if it rejects it, the connection closes with code 1.

func DialAny
func DialAny(ctx context.Context, addr string, id *koloid.Identity, cfg *Config) (*Conn, error)

DialAny is like Dial but accepts any listener key; check RemotePublicKey before trusting the connection.

func (Conn) AcceptStream
func (c *Conn) AcceptStream(ctx context.Context) (*kolotransport.Stream, error)

AcceptStream waits for the next bidirectional stream opened by the peer.

func (Conn) AcceptUniStream
func (c *Conn) AcceptUniStream(ctx context.Context) (*kolotransport.ReceiveStream, error)

AcceptUniStream waits for the next unidirectional stream opened by the peer.

func (Conn) AllowWindowGrowth
func (c *Conn) AllowWindowGrowth() bool

AllowWindowGrowth marks the connection as trusted for kolo-transport window growth, as kolotransport.Conn.AllowWindowGrowth. Call it once your own policy admits RemotePublicKey. It reports false when Config.Transport.WindowGrowth is off or the connection has ended.

func (Conn) Close
func (c *Conn) Close() error

Close closes the connection with code 0.

func (Conn) CloseWithError
func (c *Conn) CloseWithError(code uint64, msg string) error

CloseWithError closes the connection, sending code and msg to the peer, as kolotransport.Conn.CloseWithError.

func (Conn) Context
func (c *Conn) Context() context.Context

Context is canceled when the connection ends; its context.Cause is a kolo-transport error with no peer text.

func (Conn) LocalAddr
func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local UDP address.

func (Conn) OpenStream
func (c *Conn) OpenStream(ctx context.Context) (*kolotransport.Stream, error)

OpenStream opens a bidirectional stream, as kolotransport.Conn.OpenStream.

func (Conn) OpenUniStream
func (c *Conn) OpenUniStream(ctx context.Context) (*kolotransport.SendStream, error)

OpenUniStream opens a unidirectional stream, as kolotransport.Conn.OpenUniStream.

func (Conn) RemoteAddr
func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the peer's UDP address.

func (Conn) RemotePublicKey
func (c *Conn) RemotePublicKey() ed25519.PublicKey

RemotePublicKey returns a copy of the peer's kolo-id public key.

func (Conn) Stats
func (c *Conn) Stats() kolotransport.ConnStats

Stats returns the connection's statistics as kolo-transport measures them, handshake and streams together. It is cheap, never blocks, is safe from any goroutine and is the zero value once the connection has ended.

type Listener

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

Listener accepts authenticated connections on one UDP socket.

func Listen
func Listen(ctx context.Context, addr string, id *koloid.Identity, cfg *Config) (*Listener, error)

Listen opens a kolo-transport listener on addr, such as "127.0.0.1:0", and authenticates each connection as id.

func NewListener
func NewListener(tl *kolotransport.Listener, id *koloid.Identity, cfg *Config) (*Listener, error)

NewListener authenticates the connections of tl as id; it owns tl and closes it, also when it fails. cfg.Transport must be nil, since tl is already configured.

func (Listener) Accept
func (l *Listener) Accept(ctx context.Context) (*Conn, error)

Accept waits for the next connection whose peer has proved its identity; failed handshakes are skipped.

func (Listener) Addr
func (l *Listener) Addr() net.Addr

Addr returns the local address of the listener.

func (Listener) Close
func (l *Listener) Close() error

Close stops accepting, ends pending handshakes and closes every connection of the listener, accepted or not. It is safe to call more than once.

func (Listener) Dial
func (l *Listener) Dial(ctx context.Context, addr netip.AddrPort, remote ed25519.PublicKey) (*Conn, error)

Dial connects to addr from the listener's socket (kolo-transport MaxDialed bounds these) and returns once the peer has proved it holds remote. remote is checked as in Dial, and the dialer's proof is checked by the peer after Dial returns.

Good to know

Limits

kolo-secure is IPv4 only. An IPv6 address, the v4-mapped form included, is refused with ErrInvalidArgument, which also matches kolo-transport's ErrInvalidArgument. Host names resolve to IPv4 only, so a name with no IPv4 address fails with a resolve error.

Config fields (nil or zero means the default; out of range is ErrInvalidConfig):

  • HandshakeTimeout: 10s for the kolo-secure handshake after the QUIC handshake, from 1s to 60s. Past it, Dial returns ErrTimeout and the listener drops the connection.
  • MaxPending: 64 connections per listener that are handshaking or waiting for Accept, from 1 to 1000. Past it, the listener closes each new connection at once with code 1, and the dialer gets kolotransport.ErrPeerClosed. kolo-transport MaxConns (100 by default) counts these connections too.
  • Transport is passed to kolo-transport unchanged, with its limits. It must be nil for NewListener.
  • Conn.AllowWindowGrowth calls kolo-transport's AllowWindowGrowth on the connection, accepted, dialed or from Listener.Dial. Call it once your own policy admits the peer; it decides nothing itself. It returns false when Transport.WindowGrowth is off, which is the default, or when the connection has ended.
  • Conn.Stats returns kolo-transport's ConnStats for the connection, accepted, dialed or from Listener.Dial: round-trip times, bytes and packets, losses, the congestion window, the congestion controller and path changes (see kolo-transport). It is the transport's view, so the handshake and your streams count together, and kolo-secure adds nothing. It never blocks and is the zero value once the connection has ended.

Fixed values:

  • Handshake messages have a body of 1 to 256 bytes, behind a length of at most two bytes. Anything else is ErrProtocol. Every real message is at most 98 bytes.
  • remote must be a 32-byte key, not your own key and not a small-order point, or Dial returns ErrInvalidArgument.
  • A failed handshake closes the connection with application error code 1.
  • A peer that finishes QUIC and then sends nothing holds a MaxPending slot for HandshakeTimeout. With kolo-transport's MaxConnsPerIP of 4, it takes about MaxPending / MaxConnsPerIP addresses (16 at the defaults) to fill the listener, and redialing keeps it full.

Security

  • Each signature covers the protocol version, the signer's role, the 32-byte exporter value and both public keys, under the Ed25519ctx (RFC 8032) context kolo-secure/proof/v0. A proof does not verify on another connection, for the other role, or for another pair of peers. A peer that presents your own key is rejected.
  • The exporter label is EXPERIMENTAL-kolo-secure/channel-binding/v0. A relay that splices two TLS sessions gets two unrelated values, so the handshake fails on both sides.
  • The 14 encodings that Go decodes to one of the 8 small-order points are rejected by comparing bytes, before any signature is verified.
  • Dial returns once the listener has proved its key and the dialer's proof is sent. If the listener rejects that proof, it closes the connection and the dialer sees kolotransport.ErrPeerClosed with code 1.
  • Bytes the peer sends on other streams before its proof is checked reach the application only after Dial or Accept returns.
  • The dialer sends its key first, so an active prober learns it, and learns the listener's key by connecting. Passive observers see neither. Addresses, timing and sizes are visible.
  • There is no forward secrecy or rekeying beyond TLS 1.3. A stolen kolo-id key lets the thief impersonate that node on new connections.
  • Error messages include nothing the peer sent, except the numeric QUIC close or reset code that kolo-transport keeps.

Known limits

  • Experimental. The API may change before v1.0.0.
  • Version 0 accepts only version 0. There is no version negotiation.
  • Only the handshake is bounded here. After it, a connection is a plain kolo-transport connection with its limits.
  • An application that stops calling Accept fills MaxPending, and the listener then refuses everyone.
  • After NewListener, use only ReadPacket, WritePacket and Addr on the kolo-transport listener. The kolo-secure listener owns it and closes it.

Errors

ErrorMessage
ErrAuthenticationkolosecure: peer authentication failed
ErrClosedkolosecure: closed
ErrInvalidArgumentkolosecure: invalid argument
ErrInvalidConfigkolosecure: invalid config
ErrProtocolkolosecure: invalid handshake message
ErrTimeoutkolosecure: handshake timeout
ErrUnexpectedPeerkolosecure: unexpected peer key
ErrUnsupportedVersionkolosecure: unsupported handshake version

Test errors with errors.Is. An address kolo-transport refuses gives kolo-secure's ErrInvalidArgument wrapping kolo-transport's, so both match. Other kolo-transport errors, such as kolotransport.ErrPeerClosed, kolotransport.ErrHandshake or a kolotransport.ErrInvalidConfig from a bad Transport, pass through unchanged.

References