usbnet

README

i.MX Ethernet over USB driver

This Go package implements TCP/IP connectivity through Ethernet over USB (CDC-ECM) on NXP i.MX SoCs, to be used with GOOS=tamago GOARCH=arm as supported by the TamaGo framework for bare metal Go on ARM SoCs.

The CDC-ECM Ethernet over USB driver is supported natively on Linux and macOS hosts while Windows requires using third-party drivers.

The package supports TCP/IP networking through gVisor (go branch) tcpip stack pure Go implementation.

The interface TCP/IP stack can be attached to the Go runtime by setting net.SocketFunc to the interface Socket function:

iface, _ := usbnet.Init("10.0.0.1", "1a:55:89:a2:69:41", "1a:55:89:a2:69:42", 1)
net.SocketFunc = iface.Socket

See tamago-example for a full integration example.

Authors

Andrea Barisani
andrea.barisani@withsecure.com | andrea@inversepath.com

Andrej Rosano
andrej.rosano@withsecure.com | andrej@inversepath.com

Documentation

The package API documentation can be found on pkg.go.dev.

For more information about TamaGo see its repository and project wiki.

License

tamago | https://github.com/usbarmory/imx-usbnet
Copyright (c) WithSecure Corporation

These source files are distributed under the BSD-style license found in the LICENSE file.

Documentation

Overview

Package usbnet implements TCP/IP connectivity through Ethernet over USB (CDC-ECM) on i.MX6 SoCs.

The CDC-ECM Ethernet over USB driver is supported natively on Linux and macOS hosts, while Windows requires third-party drivers.

The TCP/IP stack is implemented using gVisor pure Go implementation.

This package is only meant to be used with `GOOS=tamago GOARCH=arm` as supported by the TamaGo framework for bare metal Go, see https://github.com/usbarmory/tamago.

Index

• Variables
• func ConfigureDevice(device *usb.Device, serial string)
• type Interface
  • func (iface *Interface) Add(device *usb.Device, deviceIP string, deviceMAC string, hostMAC string) (err error)
  • func (iface *Interface) DialContextTCP4(ctx context.Context, address string) (net.Conn, error)
  • func (iface *Interface) DialTCP4(address string) (net.Conn, error)
  • func (iface *Interface) DialUDP4(lAddr, rAddr string) (net.Conn, error)
  • func (iface *Interface) EnableICMP() error
  • func (iface *Interface) Init(deviceIP string, deviceMAC, hostMAC string) error
  • func (iface *Interface) ListenerTCP4(port uint16) (net.Listener, error)
  • func (iface *Interface) Socket(ctx context.Context, network string, family, sotype int, laddr, raddr net.Addr) (c interface{}, err error)
• type NIC
  • func (eth *NIC) ECMControl(_ []byte, lastErr error) (in []byte, err error)
  • func (eth *NIC) ECMRx(out []byte, lastErr error) (_ []byte, err error)
  • func (eth *NIC) ECMTx(_ []byte, lastErr error) (in []byte, err error)
  • func (eth *NIC) Init() (err error)

Variables

var (
	// MTU represents the Ethernet Maximum Transmission Unit
	MTU uint32 = 1500

	// NICID represents the default gVisor NIC identifier
	NICID = tcpip.NICID(1)

	// DefaultStackOptions represents the default gVisor Stack configuration
	DefaultStackOptions = stack.Options{
		NetworkProtocols: []stack.NetworkProtocolFactory{
			ipv4.NewProtocol,
			arp.NewProtocol},
		TransportProtocols: []stack.TransportProtocolFactory{
			tcp.NewProtocol,
			icmp.NewProtocol4,
			udp.NewProtocol},
	}
)

var MaxPacketSize uint16 = 512

MaxPacketSize represents the USB data interface endpoint maximum packet size

Functions

func ConfigureDevice

func ConfigureDevice(device *usb.Device, serial string)

ConfigureDevice configures a USB device with default descriptors for a CDC Ethernet (ECM) device, suitable for Add().

Types

type Interface

type Interface struct {
	NICID tcpip.NICID
	NIC   *NIC

	Stack *stack.Stack
	Link  *channel.Endpoint
	// contains filtered or unexported fields
}

Interface represents an Ethernet over USB interface instance.

func (*Interface) Add

func (iface *Interface) Add(device *usb.Device, deviceIP string, deviceMAC string, hostMAC string) (err error)

Add adds an Ethernet over USB configuration to a previously configured USB device, it can be used in place of Init() to create composite USB devices.

func (*Interface) DialContextTCP4

func (iface *Interface) DialContextTCP4(ctx context.Context, address string) (net.Conn, error)

DialContextTCP4 connects to an IPv4 TCP address with support for timeout supplied by ctx.

func (*Interface) DialTCP4

func (iface *Interface) DialTCP4(address string) (net.Conn, error)

DialTCP4 connects to an IPv4 TCP address.

func (*Interface) DialUDP4

func (iface *Interface) DialUDP4(lAddr, rAddr string) (net.Conn, error)

DialUDP4 creates a UDP connection to the ip:port specified by rAddr, optionally setting the local ip:port to lAddr.

func (*Interface) EnableICMP

func (iface *Interface) EnableICMP() error

EnableICMP adds an ICMP endpoint to the interface, it is useful to enable ping requests.

func (*Interface) Init

func (iface *Interface) Init(deviceIP string, deviceMAC, hostMAC string) error

Init initializes an Ethernte over USB interface (see ConfigureDevice() for its defaults) associating it to a gVisor link, a default NICID and TCP/IP gVisor Stack are set if not previously assigned.

func (*Interface) ListenerTCP4

func (iface *Interface) ListenerTCP4(port uint16) (net.Listener, error)

ListenerTCP4 returns a net.Listener capable of accepting IPv4 TCP connections for the argument port.

func (*Interface) Socket

func (iface *Interface) Socket(ctx context.Context, network string, family, sotype int, laddr, raddr net.Addr) (c interface{}, err error)

Socket can be used as net.SocketFunc under GOOS=tamago to allow its use internal use within the Go runtime.

type NIC

type NIC struct {
	// Host MAC address
	HostMAC net.HardwareAddr

	// Device MAC address
	DeviceMAC net.HardwareAddr

	// Link is a gVisor channel endpoint
	Link *channel.Endpoint

	// Device is the physical interface associated to the virtual one.
	Device *usb.Device

	// Rx is endpoint 1 OUT function, set by Init() to ECMRx if not
	// already defined.
	Rx func([]byte, error) ([]byte, error)

	// Tx is endpoint 1 IN function, set by Init() to ECMTx if not already
	// defined.
	Tx func([]byte, error) ([]byte, error)

	// Control is endpoint 2 IN function, set by Init() to ECMControl if
	// not already defined.
	Control func([]byte, error) ([]byte, error)
	// contains filtered or unexported fields
}

NIC represents an virtual Ethernet instance.

func (*NIC) ECMControl

func (eth *NIC) ECMControl(_ []byte, lastErr error) (in []byte, err error)

ECMControl implements the endpoint 2 IN function.

func (*NIC) ECMRx

func (eth *NIC) ECMRx(out []byte, lastErr error) (_ []byte, err error)

ECMRx implements the endpoint 1 OUT function, used to receive Ethernet packet from host to device.

func (*NIC) ECMTx

func (eth *NIC) ECMTx(_ []byte, lastErr error) (in []byte, err error)

ECMTx implements the endpoint 1 IN function, used to transmit Ethernet packet from device to host.

func (*NIC) Init

func (eth *NIC) Init() (err error)

Init initializes a virtual Ethernet instance on a specific USB device and configuration index.