feat: add ability to trace handshake

.github/workflows/build.yml

@@ -42,15 +42,3 @@ jobs:
         go-version: '1.20'
     - name: Ensure coverage threshold
       run: make test-coverage-threshold
-
-  integration:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - name: setup go
-        uses: actions/setup-go@v2
-        with:
-          go-version: '1.20'
-      - name: run integration tests
-        run: go test -v ./tests/integration
-

internal/controlchannel/controlchannel.go

@@ -1,3 +1,5 @@
+// Package controlchannel implements the control channel logic. The control channel sits
+// above the reliable transport and below the TLS layer.
 package controlchannel
 
 import (
@@ -36,12 +38,12 @@ type Service struct {
 //
 // [ARCHITECTURE]: https://github.com/ooni/minivpn/blob/main/ARCHITECTURE.md
 func (svc *Service) StartWorkers(
-	logger model.Logger,
+	config *model.Config,
 	workersManager *workers.Manager,
 	sessionManager *session.Manager,
 ) {
 	ws := &workersState{
-		logger:               logger,
+		logger:               config.Logger(),
 		notifyTLS:            *svc.NotifyTLS,
 		controlToReliable:    *svc.ControlToReliable,
 		reliableToControl:    svc.ReliableToControl,

internal/datachannel/controller.go

@@ -25,7 +25,7 @@ type dataChannelHandler interface {
 // DataChannel represents the data "channel", that will encrypt and decrypt the tunnel payloads.
 // data implements the dataHandler interface.
 type DataChannel struct {
-	options         *model.Options
+	options         *model.OpenVPNOptions
 	sessionManager  *session.Manager
 	state           *dataChannelState
 	decodeFn        func(model.Logger, []byte, *session.Manager, *dataChannelState) (*encryptedData, error)
@@ -39,7 +39,7 @@ var _ dataChannelHandler = &DataChannel{} // Ensure that we implement dataChanne
 // NewDataChannelFromOptions returns a new data object, initialized with the
 // options given. it also returns any error raised.
 func NewDataChannelFromOptions(log model.Logger,
-	opt *model.Options,
+	opt *model.OpenVPNOptions,
 	sessionManager *session.Manager) (*DataChannel, error) {
 	runtimex.Assert(opt != nil, "openvpn datachannel: opts cannot be nil")
 	runtimex.Assert(opt != nil, "openvpn datachannel: opts cannot be nil")

internal/datachannel/read.go

@@ -97,7 +97,7 @@ func decodeEncryptedPayloadNonAEAD(log model.Logger, buf []byte, session *sessio
 // modes are supported at the moment, so no real decompression is done. It
 // returns a byte array, and an error if the operation could not be completed
 // successfully.
-func maybeDecompress(b []byte, st *dataChannelState, opt *model.Options) ([]byte, error) {
+func maybeDecompress(b []byte, st *dataChannelState, opt *model.OpenVPNOptions) ([]byte, error) {
 	if st == nil || st.dataCipher == nil {
 		return []byte{}, fmt.Errorf("%w:%s", errBadInput, "bad state")
 	}

internal/datachannel/service.go

@@ -50,22 +50,21 @@ type Service struct {
 // 3. keyWorker BLOCKS on keyUp to read a dataChannelKey and
 // initializes the internal state with the resulting key;
 func (s *Service) StartWorkers(
-	logger model.Logger,
+	config *model.Config,
 	workersManager *workers.Manager,
 	sessionManager *session.Manager,
-	options *model.Options,
 ) {
-	dc, err := NewDataChannelFromOptions(logger, options, sessionManager)
+	dc, err := NewDataChannelFromOptions(config.Logger(), config.OpenVPNOptions(), sessionManager)
 	if err != nil {
-		logger.Warnf("cannot initialize channel %v", err)
+		config.Logger().Warnf("cannot initialize channel %v", err)
 		return
 	}
 	ws := &workersState{
 		dataChannel:          dc,
 		dataOrControlToMuxer: *s.DataOrControlToMuxer,
 		dataToTUN:            s.DataToTUN,
 		keyReady:             s.KeyReady,
-		logger:               logger,
+		logger:               config.Logger(),
 		muxerToData:          s.MuxerToData,
 		sessionManager:       sessionManager,
 		tunToData:            s.TUNToData,

internal/model/config.go

@@ -0,0 +1,92 @@
+package model
+
+import (
+	"net"
+
+	"github.com/apex/log"
+	"github.com/ooni/minivpn/internal/runtimex"
+)
+
+// Config contains options to initialize the OpenVPN tunnel.
+type Config struct {
+	// openVPNOptions contains options related to openvpn.
+	openvpnOptions *OpenVPNOptions
+
+	// logger will be used to log events.
+	logger Logger
+
+	// if a tracer is provided, it will be used to trace the openvpn handshake.
+	tracer HandshakeTracer
+}
+
+// NewConfig returns a Config ready to intialize a vpn tunnel.
+func NewConfig(options ...Option) *Config {
+	cfg := &Config{
+		openvpnOptions: &OpenVPNOptions{},
+		logger:         log.Log,
+		tracer:         &dummyTracer{},
+	}
+	for _, opt := range options {
+		opt(cfg)
+	}
+	return cfg
+}
+
+// Option is an option you can pass to initialize minivpn.
+type Option func(config *Config)
+
+// WithConfigFile configures OpenVPNOptions parsed from the given file.
+func WithConfigFile(configPath string) Option {
+	return func(config *Config) {
+		openvpnOpts, err := ReadConfigFile(configPath)
+		runtimex.PanicOnError(err, "cannot parse config file")
+		runtimex.PanicIfFalse(openvpnOpts.HasAuthInfo(), "missing auth info")
+		config.openvpnOptions = openvpnOpts
+	}
+
+}
+
+// WithLogger configures the passed [Logger].
+func WithLogger(logger Logger) Option {
+	return func(config *Config) {
+		config.logger = logger
+	}
+}
+
+// WithHandshakeTracer configures the passed [HandshakeTracer].
+func WithHandshakeTracer(tracer HandshakeTracer) Option {
+	return func(config *Config) {
+		config.tracer = tracer
+	}
+}
+
+// Logger returns the configured logger.
+func (c *Config) Logger() Logger {
+	return c.logger
+}
+
+// OpenVPNOptions returns the configured openvpn options.
+func (c *Config) OpenVPNOptions() *OpenVPNOptions {
+	return c.openvpnOptions
+}
+
+// Remote returns the openvpn remote.
+func (c *Config) Remote() *Remote {
+	return &Remote{
+		IPAddr:   c.openvpnOptions.Remote,
+		AddrPort: net.JoinHostPort(c.openvpnOptions.Remote, c.openvpnOptions.Port),
+		Protocol: c.openvpnOptions.Proto.String(),
+	}
+}
+
+// Tracer returns the handshake tracer.
+func (c *Config) Tracer() HandshakeTracer {
+	return c.tracer
+}
+
+// Remote has info about the OpenVPNRemote.
+type Remote struct {
+	IPAddr   string
+	AddrPort string
+	Protocol string
+}

internal/model/packet.go

@@ -21,8 +21,8 @@
 
 // OpenVPN packets opcodes.
 const (
 	P_CONTROL_HARD_RESET_CLIENT_V1 = Opcode(iota + 1) // 1
 	P_CONTROL_HARD_RESET_SERVER_V1                    // 2
 	P_CONTROL_SOFT_RESET_V1                           // 3
 	P_CONTROL_V1                                      // 4
 	P_ACK_V1                                          // 5
@@ -334,13 +334,8 @@
 	return p.Opcode.IsData()
 }
 
-const (
-	DirectionIncoming = iota
-	DirectionOutgoing
-)
-
 // Log writes an entry in the passed logger with a representation of this packet.
-func (p *Packet) Log(logger Logger, direction int) {
+func (p *Packet) Log(logger Logger, direction Direction) {
 	var dir string
 	switch direction {
 	case DirectionIncoming:

internal/model/trace.go

@@ -0,0 +1,75 @@
+package model
+
+import (
+	"fmt"
+	"time"
+)
+
+// HandshakeTracer allows to collect traces for a given OpenVPN handshake. A HandshakeTracer can be optionally
+// added to the top-level TUN constructor, and it will be propagated to any layer that needs to register an event.
+type HandshakeTracer interface {
+	// TimeNow allows to inject time for deterministic tests.
+	TimeNow() time.Time
+
+	// OnStateChange is called for each transition in the state machine.
+	OnStateChange(state int)
+
+	// OnIncomingPacket is called when a packet is received.
+	OnIncomingPacket(packet *Packet, stage int)
+
+	// OnOutgoingPacket is called when a packet is about to be sent.
+	OnOutgoingPacket(packet *Packet, stage int, retries int)
+
+	// OnDroppedPacket is called whenever a packet is dropped (in/out)
+	OnDroppedPacket(direction Direction, stage int, packet *Packet)
+}
+
+// Direction is one of two directions on a packet.
+type Direction int
+
+const (
+	// DirectionIncoming marks received packets.
+	DirectionIncoming = iota
+
+	// DirectionOutgoing marks packets to be sent.
+	DirectionOutgoing
+)
+
+var _ fmt.Stringer = Direction(0)
+
+// String implements fmt.Stringer
+func (d Direction) String() string {
+	switch d {
+	case DirectionIncoming:
+		return "recv"
+	case 1:
+		return "send"
+	default:
+		return "undefined"
+	}
+}
+
+// dummyTracer is a no-op implementation of [model.HandshakeTracer] that does nothing
+// but can be safely passed as a default implementation.
+type dummyTracer struct{}
+
+// TimeNow allows to manipulate time for deterministic tests.
+func (dt *dummyTracer) TimeNow() time.Time { return time.Now() }
+
+// OnStateChange is called for each transition in the state machine.
+func (dt *dummyTracer) OnStateChange(state int) {}
+
+// OnIncomingPacket is called when a packet is received.
+func (dt *dummyTracer) OnIncomingPacket(*Packet, int) {}
+
+// OnOutgoingPacket is called when a packet is about to be sent.
+func (dt *dummyTracer) OnOutgoingPacket(*Packet, int, int) {}
+
+// OnDroppedPacket is called whenever a packet is dropped (in/out)
+func (dt *dummyTracer) OnDroppedPacket(Direction, int, *Packet) {
+}
+
+func (dt *dummyTracer) OnHandshakeDone(remoteAddr string) {}
+
+// Assert that dummyTracer implements [model.HandshakeTracer].
+var _ HandshakeTracer = &dummyTracer{}