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.
The handshake
TLS 1.3 protects the bytes; the three short messages prove who holds each end.
- 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.
- Both sides derive the same 32-byte value from the TLS session (an exporter). Someone relaying in the middle would get two different values.
- On a first stream the dialer sends Hello with its kolo-id public key.
- The listener answers Proof: its public key and an Ed25519ctx signature over the exporter value and both keys.
- 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.
- 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-secureBuilds 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.
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 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() boolAllowWindowGrowth 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() errorClose closes the connection with code 0.
func (Conn) CloseWithError
func (c *Conn) CloseWithError(code uint64, msg string) errorCloseWithError closes the connection, sending code and msg to the peer, as kolotransport.Conn.CloseWithError.
func (Conn) Context
func (c *Conn) Context() context.ContextContext 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.AddrLocalAddr 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.AddrRemoteAddr returns the peer's UDP address.
func (Conn) RemotePublicKey
func (c *Conn) RemotePublicKey() ed25519.PublicKeyRemotePublicKey returns a copy of the peer's kolo-id public key.
func (Conn) Stats
func (c *Conn) Stats() kolotransport.ConnStatsStats 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.AddrAddr returns the local address of the listener.
func (Listener) Close
func (l *Listener) Close() errorClose 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,DialreturnsErrTimeoutand the listener drops the connection.MaxPending: 64 connections per listener that are handshaking or waiting forAccept, from 1 to 1000. Past it, the listener closes each new connection at once with code 1, and the dialer getskolotransport.ErrPeerClosed. kolo-transportMaxConns(100 by default) counts these connections too.Transportis passed to kolo-transport unchanged, with its limits. It must be nil forNewListener.Conn.AllowWindowGrowthcalls kolo-transport'sAllowWindowGrowthon the connection, accepted, dialed or fromListener.Dial. Call it once your own policy admits the peer; it decides nothing itself. It returns false whenTransport.WindowGrowthis off, which is the default, or when the connection has ended.Conn.Statsreturns kolo-transport'sConnStatsfor the connection, accepted, dialed or fromListener.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. remotemust be a 32-byte key, not your own key and not a small-order point, orDialreturnsErrInvalidArgument.- A failed handshake closes the connection with application error code 1.
- A peer that finishes QUIC and then sends nothing holds a
MaxPendingslot forHandshakeTimeout. With kolo-transport'sMaxConnsPerIPof 4, it takes aboutMaxPending/MaxConnsPerIPaddresses (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.
Dialreturns 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 seeskolotransport.ErrPeerClosedwith code 1.- Bytes the peer sends on other streams before its proof is checked reach
the application only after
DialorAcceptreturns. - 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
AcceptfillsMaxPending, and the listener then refuses everyone. - After
NewListener, use onlyReadPacket,WritePacketandAddron the kolo-transport listener. The kolo-secure listener owns it and closes it.
Errors
| Error | Message |
|---|---|
ErrAuthentication | kolosecure: peer authentication failed |
ErrClosed | kolosecure: closed |
ErrInvalidArgument | kolosecure: invalid argument |
ErrInvalidConfig | kolosecure: invalid config |
ErrProtocol | kolosecure: invalid handshake message |
ErrTimeout | kolosecure: handshake timeout |
ErrUnexpectedPeer | kolosecure: unexpected peer key |
ErrUnsupportedVersion | kolosecure: 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
- RFC 9846, The Transport Layer Security (TLS) Protocol Version 1.3, section 7.5, Exporters (Proposed Standard, July 2026; obsoletes RFC 8446).
- Takes: the TLS exporter value that each side signs.
- RFC 5705, Keying Material Exporters for TLS (Proposed Standard, March 2010).
- Takes: exporter labels.
- RFC 9266, Channel Bindings for TLS 1.3 (Proposed Standard, July 2022).
- Takes: the idea of the tls-exporter channel binding.
- Not implemented: the channel binding type as other protocols use it.
- RFC 8471, The Token Binding Protocol Version 1.0 (Proposed Standard, October 2018).
- Takes: the idea of signing exported keying material.
- Not implemented: its messages.
- RFC 9261, Exported Authenticators in TLS (Proposed Standard, July 2022).
- Takes: the idea of signing exported keying material.
- Not implemented: its messages.
- RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA) (Informational, January 2017).
- Takes: Ed25519ctx with the context
kolo-secure/proof/v0.
- Takes: Ed25519ctx with the context
- RFC 8827, WebRTC Security Architecture (Proposed Standard, January 2021).
- Takes: listed for the threat model.