A kolo-transport criptografa uma conexão QUIC com TLS 1.3, mas não diz quem está do outro lado. A kolo-secure acrescenta isso: depois do handshake QUIC, cada peer assina um valor do exporter TLS da conexão (RFC 9846, seção 7.5), o channel binding da RFC 9266, com a sua chave da kolo-id sob Ed25519ctx (RFC 8032), e uma conexão só é retornada depois que a assinatura do peer é confirmada. Ela só acrescenta identidade; não decide em quais chaves confiar.
O handshake
O TLS 1.3 protege os bytes; as três mensagens curtas provam quem está em cada ponta.
- O dialer abre uma conexão QUIC com TLS 1.3. O certificado é uma chave descartável, não a identidade do peer: o TLS sozinho não prova nada sobre quem está do outro lado.
- Os dois lados derivam o mesmo valor de 32 bytes da sessão TLS (um exporter). Alguém repassando no meio receberia dois valores diferentes.
- Em um primeiro stream, o dialer envia Hello com a sua chave pública do kolo-id.
- O listener responde Proof: a sua chave pública e uma assinatura Ed25519ctx sobre o valor do exporter e as duas chaves.
- O dialer confere a chave que esperava e a assinatura, depois envia Finish, a sua própria assinatura. O listener a confere antes de aceitar a conexão.
- Protegido: o conteúdo e a sua integridade, e as duas chaves. Não fica oculto: endereços IP, portas, tamanhos, ritmo e as chaves para qualquer um que se conecte.
Instalação
go get github.com/ciranda-dev/kolo-secureCompila sem cgo.
Início rápido
Duas identidades novas em 127.0.0.1. O dialer exige a chave pública do listener, e o listener devolve o que recebe em um stream.
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)
}O programa imprime a chave pública do dialer em hex e hello kolo. Um nó real
carrega a sua identidade com koloid.Load e descobre a chave do peer com o
qual abre conexão no mesmo lugar onde descobriu o endereço.
Referência da API
A referência da API é gerada a partir do código Go e está em inglês.
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.
Variáveis
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")
)Tipos
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.
Bom saber
Limites
A kolo-secure só aceita IPv4. Um endereço IPv6, incluindo a
forma v4-mapped, é recusado com ErrInvalidArgument, que também corresponde
ao ErrInvalidArgument da kolo-transport. Nomes de host só são resolvidos para
IPv4, então um nome sem endereço IPv4 falha com um erro de resolução.
Campos de Config (nil ou zero quer dizer o padrão; fora da faixa é
ErrInvalidConfig):
HandshakeTimeout: 10s para o handshake da kolo-secure depois do handshake QUIC, de 1s a 60s. Acima disso,DialretornaErrTimeoute o listener descarta a conexão.MaxPending: 64 conexões por listener que estão em handshake ou esperandoAccept, de 1 a 1000. Acima disso, o listener fecha cada nova conexão na hora com o código 1, e o dialer recebekolotransport.ErrPeerClosed. OMaxConnsda kolo-transport (100 por padrão) também conta essas conexões.Transporté passado para a kolo-transport sem mudanças, com os seus limites. Ele precisa ser nil paraNewListener.Conn.AllowWindowGrowthchamaAllowWindowGrowthda kolo-transport sobre a conexão, aceita, discada ou vinda deListener.Dial. Chame quando a sua própria política admitir o peer; ela não decide nada. Retorna false quandoTransport.WindowGrowthestá desligado, que é o padrão, ou quando a conexão terminou.Conn.Statsretorna oConnStatsda kolo-transport para a conexão, aceita, discada ou vinda deListener.Dial: tempos de ida e volta, bytes e pacotes, perdas, a janela de congestionamento, o controlador de congestionamento e as mudanças de caminho (veja kolo-transport). É a visão do transporte, então o handshake e os seus streams contam juntos, e a kolo-secure não acrescenta nada. Nunca bloqueia e é o valor zero depois que a conexão termina.
Valores fixos:
- As mensagens do handshake têm um corpo de 1 a 256 bytes, precedido por um
tamanho de no máximo dois bytes. Qualquer outra coisa é
ErrProtocol. Toda mensagem real tem no máximo 98 bytes. remoteprecisa ser uma chave de 32 bytes, não pode ser a sua própria chave nem um ponto de ordem pequena, senãoDialretornaErrInvalidArgument.- Um handshake que falha fecha a conexão com o código de erro de aplicação 1.
- Um peer que conclui o QUIC e depois não envia nada ocupa uma vaga de
MaxPendingduranteHandshakeTimeout. Com oMaxConnsPerIPde 4 da kolo-transport, são necessários cerca deMaxPending/MaxConnsPerIPendereços (16 com os padrões) para lotar o listener, e abrir conexões de novo o mantém lotado.
Segurança
- Cada assinatura cobre a versão do protocolo, o papel de quem assina, o valor
do exporter de 32 bytes e as duas chaves públicas, sob o contexto
Ed25519ctx (RFC 8032)
kolo-secure/proof/v0. Uma prova não é válida em outra conexão, para o outro papel nem para outro par de peers. Um peer que apresenta a sua própria chave é rejeitado. - O label do exporter é
EXPERIMENTAL-kolo-secure/channel-binding/v0. Um relay que emenda duas sessões TLS recebe dois valores sem relação entre si, então o handshake falha dos dois lados. - As 14 codificações que o Go decodifica para um dos 8 pontos de ordem pequena são rejeitadas por comparação de bytes, antes de verificar qualquer assinatura.
Dialretorna assim que o listener prova a sua chave e a prova do dialer é enviada. Se o listener rejeitar essa prova, ele fecha a conexão e o dialer vêkolotransport.ErrPeerClosedcom o código 1.- Os bytes que o peer envia em outros streams antes de a sua prova ser
verificada só chegam à aplicação depois que
DialouAcceptretorna. - O dialer envia a sua chave primeiro, então quem sonda ativamente descobre essa chave, e descobre a chave do listener ao se conectar. Observadores passivos não veem nenhuma das duas. Endereços, tempos e tamanhos ficam visíveis.
- Não há forward secrecy nem renovação de chaves além do que o TLS 1.3 oferece. Uma chave da kolo-id roubada permite que o ladrão se passe por aquele nó em novas conexões.
- As mensagens de erro não incluem nada que o peer enviou, a não ser o código numérico de close ou reset do QUIC que a kolo-transport guarda.
Limites conhecidos
- Experimental. A API pode mudar antes da v1.0.0.
- A versão 0 só aceita a versão 0. Não há negociação de versão.
- Aqui só o handshake tem limites. Depois dele, a conexão é uma conexão comum da kolo-transport, com os limites dela.
- Uma aplicação que para de chamar
Acceptlota oMaxPending, e o listener passa a recusar todo mundo. - Depois de
NewListener, use sóReadPacket,WritePacketeAddrno listener da kolo-transport. O listener da kolo-secure é o dono dele e o fecha.
Erros
| Erro | Mensagem |
|---|---|
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 |
Teste os erros com errors.Is. Um endereço que a kolo-transport recusa gera o
ErrInvalidArgument da kolo-secure envolvendo o da kolo-transport, então os
dois correspondem. Outros erros da kolo-transport, como
kolotransport.ErrPeerClosed, kolotransport.ErrHandshake ou um
kolotransport.ErrInvalidConfig vindo de um Transport inválido, passam
adiante sem mudanças.
Referências
- RFC 9846, The Transport Layer Security (TLS) Protocol Version 1.3, seção 7.5, Exporters (Proposed Standard, July 2026; obsoletes RFC 8446).
- Usa: o valor do exporter TLS que cada lado assina.
- RFC 5705, Keying Material Exporters for TLS (Proposed Standard, March 2010).
- Usa: os rótulos do exporter.
- RFC 9266, Channel Bindings for TLS 1.3 (Proposed Standard, July 2022).
- Usa: a ideia do channel binding tls-exporter.
- Não implementa: o tipo de channel binding como outros protocolos o usam.
- RFC 8471, The Token Binding Protocol Version 1.0 (Proposed Standard, October 2018).
- Usa: a ideia de assinar o material de chaves exportado.
- Não implementa: as suas mensagens.
- RFC 9261, Exported Authenticators in TLS (Proposed Standard, July 2022).
- Usa: a ideia de assinar o material de chaves exportado.
- Não implementa: as suas mensagens.
- RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA) (Informational, January 2017).
- Usa: Ed25519ctx com o contexto
kolo-secure/proof/v0.
- Usa: Ed25519ctx com o contexto
- RFC 8827, WebRTC Security Architecture (Proposed Standard, January 2021).
- Usa: listada para o modelo de ameaças.