wire

package
v0.0.72 Latest Latest
Warning

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

 Go to latest Published: Feb 4, 2026 License: AGPL-3.0, AGPL-3.0 Imports: 23 Imported by: 1

Documentation

Overview

Package wire implements the Katzenpost wire protocol.

Index

Constants

View Source 
const (
	// MaxAdditionalDataLength is the maximum length of the additional data
	// sent to the peer as part of the handshake authentication.
	MaxAdditionalDataLength = 255

	// MaxMessageSize is the maximum allowed message size we are willing to send or receive.
	// Note that this doesn't apply Storage Replicas because they have command sets which are fixed size.
	// Everyone else besides the storage servers DO NOT have fixed sized command sets because they
	// send arbitrary sized PKI documents and the like. Therefore this maximum constant is only applicable
	// to wire protocol connections among the dirauths and among the mix nodes.
	MaxMessageSize = 500000000
)

Variables

This section is empty.

Functions

func GetDebugError added in v0.0.67 

func GetDebugError(err error) string

GetDebugError returns detailed error information if available. WARNING: This output contains sensitive information (IP addresses, key material) and should ONLY be logged at DEBUG level.

func IsAuthenticationError added in v0.0.58 

func IsAuthenticationError(err error) bool

IsAuthenticationError checks if an error is an AuthenticationError

func IsHandshakeError added in v0.0.58 

func IsHandshakeError(err error) bool

IsHandshakeError checks if an error is a HandshakeError

func IsMessageSizeError added in v0.0.58 

func IsMessageSizeError(err error) bool

IsMessageSizeError checks if an error is a MessageSizeError

func IsProtocolVersionError added in v0.0.58 

func IsProtocolVersionError(err error) bool

IsProtocolVersionError checks if an error is a ProtocolVersionError

Types

type AuthenticationError added in v0.0.58 

type AuthenticationError struct {
	PeerCredentials *PeerCredentials
	AdditionalData  []byte
	Connection      *ConnectionInfo
	ClockSkew       int64
}

AuthenticationError represents a peer authentication failure

func (*AuthenticationError) Debug added in v0.0.67 

func (e *AuthenticationError) Debug() string

Debug returns a detailed error message with all available information. WARNING: This output contains sensitive information (IP addresses, key material) and should ONLY be logged at DEBUG level.

func (*AuthenticationError) Error added in v0.0.58 

func (e *AuthenticationError) Error() string

Error implements the error interface. Note: This method intentionally excludes sensitive information like IP addresses and key material. Use Debug() for detailed information at debug log level only.

type ConnectionInfo added in v0.0.58 

type ConnectionInfo struct {
	Protocol   string // "tcp", "tcp4", "tcp6", "quic", "udp", etc.
	LocalAddr  string // Local IP:port
	RemoteAddr string // Remote IP:port
	LocalIP    string // Local IP address only
	RemoteIP   string // Remote IP address only
	LocalPort  string // Local port only
	RemotePort string // Remote port only
	PeerName   string // Optional: human-readable peer identifier (e.g., authority name)
}

ConnectionInfo provides detailed network connection information

func ExtractConnectionInfo added in v0.0.58 

func ExtractConnectionInfo(conn interface{}) *ConnectionInfo

ExtractConnectionInfo extracts detailed connection information from net.Conn

type DebugError added in v0.0.67 

type DebugError interface {
	error
	Debug() string
}

DebugError interface for errors that can provide detailed information. WARNING: The Debug() method returns sensitive information (IP addresses, key material) and should ONLY be logged at DEBUG level.

type HandshakeError added in v0.0.58 

type HandshakeError struct {
	State           HandshakeState
	Message         string
	UnderlyingError error
	IsInitiator     bool

	// Key material information
	LocalStaticKey  kem.PublicKey
	RemoteStaticKey kem.PublicKey

	// Protocol information
	ProtocolName string
	KEMScheme    string

	// Message information
	MessageNumber int
	MessageSize   int
	ExpectedSize  int

	// Authentication information
	AdditionalData  []byte
	PeerCredentials *PeerCredentials

	// Network information
	Connection *ConnectionInfo
}

HandshakeError provides comprehensive information about handshake failures

func GetHandshakeError added in v0.0.58 

func GetHandshakeError(err error) (*HandshakeError, bool)

GetHandshakeError returns the HandshakeError if the error is one, unwrapping the error chain if necessary.

func NewHandshakeError added in v0.0.58 

func NewHandshakeError(state HandshakeState, message string, err error) *HandshakeError

NewHandshakeError creates a new HandshakeError with the given parameters

func (*HandshakeError) Debug added in v0.0.67 

func (e *HandshakeError) Debug() string

Debug returns a detailed error message with all available information. WARNING: This output contains sensitive information (IP addresses, key material) and should ONLY be logged at DEBUG level.

func (*HandshakeError) Error added in v0.0.58 

func (e *HandshakeError) Error() string

Error implements the error interface. Note: This method intentionally excludes sensitive information like IP addresses and key material. Use Debug() for detailed information at debug log level only.

func (*HandshakeError) WithPeerName added in v0.0.70 

func (e *HandshakeError) WithPeerName(name string) *HandshakeError

WithPeerName sets the peer name on the error's connection info. If Connection is nil, it creates a new ConnectionInfo. Returns the error for chaining.

type HandshakeState added in v0.0.58 

type HandshakeState string

HandshakeState represents the current state of the handshake 

const (
	HandshakeStateInit           HandshakeState = "initialization"
	HandshakeStateMsg1Send       HandshakeState = "message_1_send"
	HandshakeStateMsg1Receive    HandshakeState = "message_1_receive"
	HandshakeStateMsg2Send       HandshakeState = "message_2_send"
	HandshakeStateMsg2Receive    HandshakeState = "message_2_receive"
	HandshakeStateMsg3Send       HandshakeState = "message_3_send"
	HandshakeStateMsg3Receive    HandshakeState = "message_3_receive"
	HandshakeStateMsg4Send       HandshakeState = "message_4_send"
	HandshakeStateMsg4Receive    HandshakeState = "message_4_receive"
	HandshakeStateAuthentication HandshakeState = "peer_authentication"
	HandshakeStateFinalization   HandshakeState = "finalization"
)

type MessageSizeError added in v0.0.58 

type MessageSizeError struct {
	MessageNumber int
	ActualSize    int
	ExpectedSize  int
	MaxSize       int
	State         HandshakeState
}

MessageSizeError represents a message size validation error

func (*MessageSizeError) Debug added in v0.0.67 

func (e *MessageSizeError) Debug() string

Debug returns a detailed error message with all available information. Note: MessageSizeError does not contain sensitive information, but implements the DebugError interface for consistency with other wire error types.

func (*MessageSizeError) Error added in v0.0.58 

func (e *MessageSizeError) Error() string

type PeerAuthenticator 

type PeerAuthenticator interface {
	// IsPeerValid authenticates the remote peer's credentials, returning true
	// iff the peer is valid.
	IsPeerValid(*PeerCredentials) bool
}

PeerAuthenticator is the interface used to authenticate the remote peer, based on the authenticated key exchange.

type PeerCredentials 

type PeerCredentials struct {
	AdditionalData []byte
	PublicKey      kem.PublicKey
}

PeerCredentials is the peer's credentials received during the authenticated key exchange. By virtue of the Noise Protocol's design, the AdditionalData is guaranteed to have been sent from a peer possessing the private component of PublicKey.

type ProtocolVersionError added in v0.0.58 

type ProtocolVersionError struct {
	Expected   []byte
	Received   []byte
	Connection *ConnectionInfo
}

ProtocolVersionError represents a protocol version mismatch

func (*ProtocolVersionError) Debug added in v0.0.67 

func (e *ProtocolVersionError) Debug() string

Debug returns a detailed error message with all available information. WARNING: This output contains sensitive information (IP addresses) and should ONLY be logged at DEBUG level.

func (*ProtocolVersionError) Error added in v0.0.58 

func (e *ProtocolVersionError) Error() string

Error implements the error interface. Note: This method intentionally excludes sensitive information like IP addresses. Use Debug() for detailed information at debug log level only.

type Session 

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

Session is a wire protocol session.

func NewPKISession 

func NewPKISession(cfg *SessionConfig, isInitiator bool) (*Session, error)

NewPKISession creates a new session to be used with the PKI (authority). Unlike NewSession, NewPKISession does not require that you pass in a Sphinx geometry.

func NewSession 

func NewSession(cfg *SessionConfig, isInitiator bool) (*Session, error)

NewSession creates a new Session.

func NewStorageReplicaSession added in v0.0.44 

func NewStorageReplicaSession(cfg *SessionConfig, scheme nike.Scheme, isInitiator bool) (*Session, error)

NewStorageReplicaSession creates a new session to be used with the storage replicas.

func (*Session) ClockSkew 

func (s *Session) ClockSkew() time.Duration

ClockSkew returns the approximate clock skew based on the responder's timestamp received as part of the handshake. This call MUST only be called from a session that has successfully completed Initialize(), and the peer is the responder.

func (*Session) Close 

func (s *Session) Close()

Close terminates a session.

func (*Session) GetCommands added in v0.0.33 

func (s *Session) GetCommands() *commands.Commands

func (*Session) Initialize 

func (s *Session) Initialize(conn net.Conn) error

Initialize takes an establised net.Conn, and binds it to a Session, and conducts the wire protocol handshake.

func (*Session) MaxMesgSize added in v0.0.44 

func (s *Session) MaxMesgSize() int

func (*Session) PeerCredentials 

func (s *Session) PeerCredentials() (*PeerCredentials, error)

PeerCredentials returns the peer's credentials. This call MUST only be called from a session that has successfully completed Initialize().

func (*Session) RecvCommand 

func (s *Session) RecvCommand() (commands.Command, error)

RecvCommand receives a wire protocol command off the network.

func (*Session) SendCommand 

func (s *Session) SendCommand(cmd commands.Command) error

SendCommand sends the wire protocol command cmd.

type SessionConfig 

type SessionConfig struct {

	// KEMScheme wire/link protocol KEM scheme.
	KEMScheme kem.Scheme

	// PKISignatureScheme specifies the cryptographic signature scheme
	PKISignatureScheme sign.Scheme

	// Authenticator is the PeerAuthenticator instance that will be used to
	// authenticate the remote peer for the newly created Session.
	Authenticator PeerAuthenticator

	// AdditionalData is the additional data that will be passed to the peer
	// as part of the wire protocol handshake, the length of which MUST be less
	// than or equal to MaxAdditionalDataLength.
	AdditionalData []byte

	// AuthenticationKey is the static long term authentication key used to
	// authenticate with the remote peer.
	AuthenticationKey kem.PrivateKey

	// RandomReader is a cryptographic entropy source.
	RandomReader io.Reader

	// Geometry is the geometry of the Sphinx cryptographic packets
	// that we will use with our wire protocol.
	Geometry *geo.Geometry
}

SessionConfig is the configuration used to create new Sessions.

type SessionInterface 

type SessionInterface interface {
	Initialize(conn net.Conn) error
	SendCommand(cmd commands.Command) error
	RecvCommand() (commands.Command, error)
	Close()
	PeerCredentials() (*PeerCredentials, error)
	ClockSkew() time.Duration
}

SessionInterface is the interface used to initialize or teardown a Session and send and receive command.Commands.

Source Files

View all Source files

Directories

Path Synopsis
Wire protocol commands.
 Wire protocol commands.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.